Skip to content

feat: introduce raw mdast linter #275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 17 commits into from
May 28, 2025
Merged

Conversation

araujogui
Copy link
Member

@araujogui araujogui commented May 20, 2025

Description

Refactors the linter engine to operate directly on raw AST nodes, removing the use of metadata entries.

This expands future linting capabilities and enables more precise issue location reporting.

Validation

npx api-docs-tooling lint -i doc/api/*.md

Related Issues

Related #271

Check List

  • I have read the Contributing Guidelines and made commit messages that follow the guideline.
  • I have run node --run test and all tests passed.
  • I have check code formatting with node --run format & node --run lint.
  • I've covered new added functionality with unit tests if necessary.

@araujogui araujogui requested a review from a team as a code owner May 20, 2025 00:08
@araujogui
Copy link
Member Author

CC @nodejs/web-infra

Copy link
Member

@AugustinMauroy AugustinMauroy left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGMT !

@avivkeller avivkeller merged commit 0e27580 into nodejs:main May 28, 2025
6 checks passed
@ovflowd
Copy link
Member

ovflowd commented May 28, 2025

I didn't had time to review this PR, so giving a review to be acted as a follow-up.

const lint = (file, tree) => {
const context = createContext(file, tree);

for (const rule of rules) {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: Why not forEach?


return issues;
// Process blockquotes to find stability nodes
if (node.type === 'blockquote') {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Way too many nested if statements. This is really not ideal. If you have more than 2-3 nested statements this shows an underlying issue.

Reading and understanding this code becomes extremely hard. Please refactor and ensure you don't need all these statements.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, linting shouldn't not be something complex and resource intensive, wonder if this linting rule is strictly necessary and not accidentally too complex.

.forEach(version =>
context.report({
level: 'error',
message: version
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assign this to a constant, quite hard to read.

Copy link
Member

@ovflowd ovflowd left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel we need more documentation around this + how to contribute and create new linting rules.

I do believe we should introduce an interface/factory system for linting rules and normalizing this. It feels like we're overcomplicating things and some of the code has barely any documentation and barely explains what it is doing and why. This sort of code needs to be easy to read and ton understand and the linting rules need to be natively friendly for folks to understand how they work and why.

If possible please do an overhaul, cleanup, inline documentation, contribution documentation/guidelines + explaining how the linting system works.

I'd also appreciate a benchmark of just linting and then linting + normal run.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants