feat(linter): Implement jsdoc/check-access

[leaysgur]

Part of #1170, Finally... 🗻

Some preparation PRs may be needed in advance.

• settings.jsdoc feat(linter): Add settings.jsdoc #2706
• new struct design refactor(semantic/jsdoc): JSDocTag parser rework #2765
• handle Span for diagnostics feat(semantic/jsdoc): Add Span for JSDoc, JSDocTag #2815

Implement plugin itself.

• https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/check-access.md
• https://github.com/gajus/eslint-plugin-jsdoc/blob/main/src/rules/checkAccess.js

I'll send a PR to make this plugin public after confirming that a few more rules can be implemented without any problems.

[leaysgur]

@Boshen These are some concerns noticed when I tried it. What do you think?

Is it OK to use run_once?

I got a review in a previous PR: If run_once is implemented, but run is still executed.

Is this unavoidable?

Resolved

struct JSDocTag

Currently, there is a single struct JSDocTag and distinguished by its .kind.

Should there be a separate struct for each tag?
Then, for example, something like has_valid_level() could be implemented in JSDocAccessTag.

But current string based implementation also looks fine for me.
(There is no specification of how users actually describe JSDoc. 🙄 )

It depends on how deeply Oxc wants to support JSDoc?

Failed CI

(I'm not sure I can fix this...!)

This is the failed comments from antd.mjs.

/**
 * flat tree data on expanded state
 *
 * @export
 * @template T
 * @param {*} data : table data
 * @param {string} childrenColumnName : 指定树形结构的列名
 * @param {Set<Key>} expandedKeys : 展开的行对应的keys
 * @param {GetRowKey<T>} getRowKey  : 获取当前rowKey的方法
 * @returns flattened data
 */

Something wrong in @param parsing?
(BTW, why this does not happen in main branch...?)

UPDATE: maybe should fix &self.source_text[start..self.current]...? + using chars() to char_indices() everywhere...?

[codspeed-hq]

CodSpeed Performance Report

Merging #2642 will improve performances by 6.82%

_{Comparing plugin-jsdoc/check-access (ab77d00) with main (6823482)}

Summary

⚡ 1 improvements
✅ 35 untouched benchmarks

Benchmarks breakdown

	Benchmark	main	plugin-jsdoc/check-access	Change
⚡	sourcemap[react.development.js]	21 ms	19.6 ms	+6.82%

[Boshen]

Is it OK to use run_once?

This is the work flow:

oxc/crates/oxc_linter/src/lib.rs

Lines 107 to 129 in 53a8e7f

	pub fn run<'a>(&self, ctx: LintContext<'a>) -> Vec<Message<'a>> {
	let semantic = Rc::clone(ctx.semantic());
	let mut ctx =
	ctx.with_fix(self.options.fix).with_settings(&self.settings).with_env(&self.env);
	for (rule_name, rule) in &self.rules {
	ctx.with_rule_name(rule_name);
	rule.run_once(&ctx);
	}
	for symbol in semantic.symbols().iter() {
	for (rule_name, rule) in &self.rules {
	ctx.with_rule_name(rule_name);
	rule.run_on_symbol(symbol, &ctx);
	}
	}
	for node in semantic.nodes().iter() {
	for (rule_name, rule) in &self.rules {
	ctx.with_rule_name(rule_name);
	rule.run(node, &ctx);
	}
	}

We try to avoid visiting the AST twice.

---

Should there be a separate struct for each tag?

Do this instead:

impl<'a> JSDocTag<'a> {
    fn kind(&self) -> JSDocTagKind<'a> {
        self.kind
    }
}

impl<'a> JSDocTagKind<'a> {
    fn is_deprecated(&self) -> bool {
        matches!(self, Self::Deprecated)
    }

    fn parameter(&self) -> Option<&Param<'a>> {
        if let Self::Parameter(param) = self {
            Some(param)
        } else {
            None
        }
    }
}

I think this is easier than many nodes containing comment and then a trait implemented on each node for retrieving the comment ...

[leaysgur]

Thanks!

This is the work flow:

Many of plugin-jsdoc rules will use run_once() only.

In these cases,

for node in semantic.nodes().iter() { 
   for (rule_name, rule) in &self.rules { 
       ctx.with_rule_name(rule_name); 
       rule.run(node, &ctx); // this run() fn is almost empty 👀 
   } 
} 

Does this mean negligibly cheep?

Or should consider something like:

for node in semantic.nodes().iter() { 
   for (rule_name, rule) in &self.rules { 
       if rule.can_skip_run { continue; } // <-
       ctx.with_rule_name(rule_name); 
       rule.run(node, &ctx);
   } 
} 

?

[leaysgur]

@Boshen Thanks for merging #2893 , how about this PR?

[Boshen]

Thank you! Sorry I missed the PR.