Change Request: Using `cheerio` library instead of manual regex for handling HTML

[lumirlumir]

Environment

ESLint version: HEAD
@eslint/markdown version: HEAD
Node version: 20.18.0
npm version: 10.9.2
Operating System: Windows 11

What problem do you want to solve?

@eslint/eslint-team

Hi team 😄

I’d like to suggest using the cheerio library instead of manual regex for handling HTML, as it would provide a more robust and reliable approach.

(Handling HTML directly may not be the main focus for the team, since the prelint feature is currently under RFC. However, HTML is a standard feature of CommonMark, and we already have a lot of logic built around it. That’s why I believe this change is necessary.)

---

While working on the @eslint/markdown repository, I’ve seen a lot of regex-related fixes. Since Markdown handles natural text, sometimes regex is unavoidable.

However, lately many fixes have focused on false positives or negatives with HTML nodes, as seen in these issues and PRs:

• Ongoing:
  • Rule Change: Improve HTML id/name attribute parsing in no-missing-link-fragments #481,
  • Bug: no-multiple-h1 and require-alt-text miss errors after a HTML comment is closed #464,
  • fix: improve HTML id/name regex for unquoted values and spaces #480,
  • fix: detect errors after comments in no-multiple-h1 and require-alt-text #468
• Merged:
  • fix: potential super-linear regular expressions #463,
  • fix: case-insensitive attribute checks in no-missing-link-fragment #465,
  • fix: update require-alt-text rule to ignore commented images #385

Manual regex for HTML nodes worked fine initially, but as the project has grown and more users are adopting this plugin, more problems are cropping up. Some examples:

• False positives and negatives
• Inconsistent HTML node handling across rules
• Potential security issues (ReDos)
• Increased maintenance cost for reviewing regex-related issues and writing robust patterns

Because of all this, there’s a growing need for consistent HTML node handling.

So, I’d like to propose introducing cheerio for HTML node handling.

Here are some pros and cons:

Pros:

• More robust code with fewer false positives/negatives
• Consistent HTML node handling across the repository, reducing maintenance cost
• Safer from ReDos attacks (We already have merged a PR about this)
• Less time spent reviewing and maintaining custom regex

Cons:

• Adds a new dependency
• Some learning curve for the library
• There’s an ongoing RFC for using prelint for HTML handling (though I’m not sure this covers all cases, since HTML is a standard part of CommonMark and we already have a lot of logic around it; a quicker solution may be needed, as prelint could take a while)

---

As for the roadmap, I don’t think the transition would be too costly:

• For ongoing issues/PRs: Authors could switch to cheerio instead of regex
• For others: I’m happy to take this on and refactor as needed

What do you think is the correct solution?

I’d like to suggest using the cheerio library instead of manual regex for handling HTML, as it would provide a more robust and reliable approach.

Participation

• I am willing to submit a pull request for this change.

Additional comments

If it would help make things more robust and reliable, I’m open to other suggestions. Let’s think about how we can handle HTML nodes in a consistent and safe way.

[nzakas]

Thanks for the suggestion. cheerio is over 6 MB, and I don't think it's worth the extra size to solve this case.

I'd suggest looking for some smaller alternatives that can address the same problem.

[lumirlumir]

cheerio is over 6 MB, and I don't think it's worth the extra size to solve this case.

@nzakas Thanks for taking a look at this issue.

I hadn't realized how large it is and how many dependencies it brings in. That's a great point.

---

After some research, I found a lightweight alternative: ultrahtml.

This package is only 368KB and has no dependencies.

It also provides APIs like querySelector and querySelectorAll, similar to the DOM, which should make it straightforward for authors to use. I spent a few hours testing it locally, and it seems to work well for my needs.

Additionally, it’s maintained by a trusted author and is used by quite a few projects, so I think it’s stable enough for production use.

---

I’d love to hear your thoughts on this alternative, ultrahtml.

[nzakas]

ultrahtml looks like a good alternative. 368kb is still kind of large for basic HTML parsing (I suspect a lot of this size has to do with CSS selector parsing), but definitely better than 6MB. Let's give it a shot.

[snitin315]

I'm also 👍🏻 for ultrahtml adoption.

[lumirlumir]

@nzakas

I suspect a lot of this size has to do with CSS selector parsing

Based on your comments, I took a closer look and found that many parts of ultrahtml aren’t necessary for our (linting) use case:

• JSX runtime: Not needed, since we’re just parsing HTML.
• Async functions: We don’t need async logic in rules.
• Sanitization: Our goal is linting, not sanitizing HTML.
• parsel-js: As you pointed out, CSS selector parsing isn’t needed. (parsel-js is the CSS selector library used internally by ultrahtml.)

If we extract only the logic we actually need from ultrahtml, the bundle size should drop dramatically—likely under 1000 lines of code (excluding tests).

How do you feel about extracting just the necessary logic from ultrahtml into our project? The codebase isn’t huge, so I think it could be done pretty smoothly.

[nzakas]

I'm okay with extracting the logic. Let's just be sure that we maintain the license information.

[lumirlumir]

The ultrahtml project uses the MIT license.

I'll make sure to maintain the license information while working on this task.

[lumirlumir]

Hi, @nzakas

If it is okay, could you give some advice on this issue whenever you have time?

---

While working on #489, I ran into a challenge: the current ultrahtml parser isn't fully HTML spec-compliant. It's lightweight and simple, but this leads to some false positives in certain edge cases.

I tried improving ultrahtml myself, but making it more compliant turned out to be difficult and time-consuming. I realize we may not need 100% compliance, but I'm concerned about possible unexpected behavior as the project grows.

I've looked into alternatives for 100% HTML spec compliance, but the lightest fully compliant parser I found is parse5, which is 877KB (48KB gzipped). It's significantly heavier than ultrahtml, but it would give us full HTML spec compatibility.

(For reference, parse5 is already used in hast, which is part of the same ecosystem as Mdast, cheerio, and other related tools.)

So, I see two options:

1. Adopt parse5 for full compliance, at the cost of increased size.
2. Stick with a lightweight, mostly-compliant approach (as now), accepting some spec deviations.

I'd appreciate your thoughts on whether we should prioritize 100% HTML compliance, or if a "good enough" approach is acceptable for this project.

Thank you!