feat(no-use, require-description): additionalDirectives option

[brettz9]

Fixes #265.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.95%. Comparing base (e0f326f) to head (e54917c).
⚠️ Report is 18 commits behind head on main.

❗ There is a different number of reports uploaded between BASE (e0f326f) and HEAD (e54917c). Click for more details.

HEAD has 41 uploads less than BASE

Flag	BASE (e0f326f)	HEAD (e54917c)
	56	15

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #267      +/-   ##
==========================================
- Coverage   97.87%   91.95%   -5.93%     
==========================================
  Files          17       18       +1     
  Lines         282      323      +41     
==========================================
+ Hits          276      297      +21     
- Misses          6       26      +20     

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

[ota-meshi]

Could you please add documentation for the new options?
It would also be useful for users to note that in the require-description rule, the comment format for additional directives must follow ESLint's directive format (directive -- description).

[brettz9]

Could you please add documentation for the new options?

My apologies—added.

It would also be useful for users to note that in the require-description rule, the comment format for additional directives must follow ESLint's directive format (directive -- description).

Sure, done.

[lumirlumir]

I'm also fairly new to this codebase, so, I have left comments only on the parts I could clearly identify. :)

[ota-meshi]

I noticed that comments are included in nodes in markdown's AST (not comments property).

https://github.com/eslint/markdown/blob/main/src/language/markdown-source-code.js

This means that the additionalDirectives option cannot be used with markdown.
I think we should change it so that if the sourceCode don't have either getAllComments() or ast.comments, the additionalDirectives option is ignored and we use getAllDirectiveCommentsFromInlineConfigNodes().
We may also need to document this behavior.

[brettz9]

I've added a commit which I think should support Markdown (since it's now checking for .ast.comments as well as .comments)—let me know if you want me to add @eslint/markdown to devDependencies and test it, but I have documented the fact that we may not be able to successfully find comments.

[lumirlumir]

Just a quick question here.

As far as I know, the Markdown plugin's MarkdownSourceCode and its AST do not include ast.comments.

Code Explorer Example.

Currently, there is no direct way or public API to access Markdown's AST comments. It only yields HTML, so if we want to extract comments, I think we'd need to pull them from that HTML.

Am I missing something here?

[brettz9]

Just a quick question here.

As far as I know, the Markdown plugin's MarkdownSourceCode and its AST do not include ast.comments.

Code Explorer Example.

Currently, there is no direct way or public API to access Markdown's AST comments. It only yields HTML, so if we want to extract comments, I think we'd need to pull them from that HTML.

Am I missing something here?

No, you're right. I had just been thinking that .ast.comments could exist because there was .ast (and was vaguely thinking maybe comments in fenced JavaScript blocks could be there, but I see that is not the case). Since the intent here is really just to support the JavaScript-style comments, maybe we can leave any HTML comment parsing to another PR.

[lumirlumir]

Thanks for confirming!

Thinking about it more, I think this issue can be easily resolved by supporting access to its comments via MarkdownSourceCode#comments, similar to how the JSON/CSS language does.

Could I get some more opinions on this? @ota-meshi @brettz9

I think adding a new public API to expose MarkdownSourceCode#comments would make sense for the use cases here and for consistency with other language plugins. I can open a separate issue in @eslint/markdown if others think that's appropriate.

[brettz9]

SGTM if there is no problem with potential confusability with JavaScript comments using the same API.

[lumirlumir]

Great — I'll work on this soon, and I hope this PR can be merged shortly after we drop support for older ESLint and Node.js versions, as it includes some workarounds in comments and tests. Please bear with me for a little while.