dan/oxc
1
0
Fork 0
mirror of https://github.com/danbulant/oxc synced 2026-05-19 12:19:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(linter): add docs for ContextHost and LintContext (#6272)

Browse source 
- towards https://github.com/oxc-project/oxc/issues/5870

Adds some very basic docs for methods and properties related to `LintContext` and `ContextHost`.
This commit is contained in:
camchenry 2024-10-04 01:41:32 +00:00 committed by Cameron McHenry
parent 2f888ed871
commit 7ca70ddab6
2 changed files with 64 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

21
crates/oxc_linter/src/context/host.rs
View file

@ -34,7 +34,11 @@ use super::{plugin_name_to_prefix, LintContext};
#[must_use]
#[non_exhaustive]
pub(crate) struct ContextHost<'a> {
/// Shared semantic information about the file being linted, which includes scopes, symbols
/// and AST nodes. See [`Semantic`].
pub(super) semantic: Rc<Semantic<'a>>,
/// Information about specific rules that should be disabled or enabled, via comment directives like
/// `eslint-disable` or `eslint-disable-next-line`.
pub(super) disable_directives: DisableDirectives<'a>,
/// Diagnostics reported by the linter.
///
@ -46,9 +50,14 @@ pub(crate) struct ContextHost<'a> {
/// Set via the `--fix`, `--fix-suggestions`, and `--fix-dangerously` CLI
/// flags.
pub(super) fix: FixKind,
/// Path to the file being linted.
pub(super) file_path: Box<Path>,
/// Global linter configuration, such as globals to include and the target
/// environments, and other settings.
pub(super) config: Arc<LintConfig>,
/// Front-end frameworks that might be in use in the target file.
pub(super) frameworks: FrameworkFlags,
/// A list of all available linter plugins.
pub(super) plugins: LintPlugins,
}
@ -88,12 +97,14 @@ impl<'a> ContextHost<'a> {
.sniff_for_frameworks()
}
/// Set the linter configuration for this context.
#[inline]
pub fn with_config(mut self, config: &Arc<LintConfig>) -> Self {
self.config = Arc::clone(config);
self
}
/// Shared reference to the [`Semantic`] analysis of the file.
#[inline]
pub fn semantic(&self) -> &Semantic<'a> {
&self.semantic
@ -115,12 +126,14 @@ impl<'a> ContextHost<'a> {
self.semantic.source_type()
}
/// Add a diagnostic message to the end of the list of diagnostics. Can be used
/// by any rule to report issues.
#[inline]
pub(super) fn push_diagnostic(&self, diagnostic: Message<'a>) {
self.diagnostics.borrow_mut().push(diagnostic);
}
/// Take all diagnostics collected during linting.
/// Take ownership of all diagnostics collected during linting.
pub fn take_diagnostics(&self) -> Vec<Message<'a>> {
// NOTE: diagnostics are only ever borrowed here and in push_diagnostic.
// The latter drops the reference as soon as the function returns, so
@ -129,6 +142,7 @@ impl<'a> ContextHost<'a> {
std::mem::take(&mut *messages)
}
/// Creates a new [`LintContext`] for a specific rule.
pub fn spawn(self: Rc<Self>, rule: &RuleWithSeverity) -> LintContext<'a> {
let rule_name = rule.name();
let plugin_name = self.map_jest(rule.plugin_name(), rule_name);
@ -144,6 +158,7 @@ impl<'a> ContextHost<'a> {
}
}
/// Creates a new [`LintContext`] for testing purposes only.
#[cfg(test)]
pub(crate) fn spawn_for_test(self: Rc<Self>) -> LintContext<'a> {
LintContext {
@ -157,6 +172,10 @@ impl<'a> ContextHost<'a> {
}
}
/// Maps Jest rule names and maps to Vitest rules when possible, returning the original plugin otherwise.
///
/// Many Vitest rules are essentially ports of the Jest plugin rules with minor modifications.
/// For these rules, we use the corresponding jest rules with some adjustments for compatibility.
fn map_jest(&self, plugin_name: &'static str, rule_name: &str) -> &'static str {
if self.plugins.has_vitest()
&& plugin_name == "jest"

47
crates/oxc_linter/src/context/mod.rs
View file

@ -22,17 +22,28 @@ pub(crate) use host::ContextHost;
#[derive(Clone)]
#[must_use]
/// Contains all of the state and context specific to this lint rule. Includes information
/// like the rule name, plugin name, and severity of the rule. It also has a reference to
/// the shared linting data [`ContextHost`], which is the same for all rules.
pub struct LintContext<'a> {
/// Shared context independent of the rule being linted.
parent: Rc<ContextHost<'a>>,
// states
/// Name of the plugin this rule belongs to. Example: `eslint`, `unicorn`, `react`
current_plugin_name: &'static str,
/// Prefixed version of the plugin name. Examples:
/// - `eslint-plugin-react`, for `react` plugin,
/// - `typescript-eslint`, for `typescript` plugin,
/// - `eslint-plugin-import`, for `import` plugin.
current_plugin_prefix: &'static str,
/// Kebab-cased name of the current rule being linted. Example: `no-unused-vars`, `no-undef`.
current_rule_name: &'static str,
/// Capabilities of the current rule to fix issues. Indicates whether:
/// - Rule cannot be auto-fixed [`RuleFixMeta::None`]
/// - Rule needs an auto-fix to be written still [`RuleFixMeta::FixPending`]
/// - Rule can be fixed in some cases [`RuleFixMeta::Conditional`]
/// - Rule is fully auto-fixable [`RuleFixMeta::Fixable`]
#[cfg(debug_assertions)]
current_rule_fix_capabilities: RuleFixMeta,
/// Current rule severity. Allows for user severity overrides, e.g.
/// ```json
/// // .oxlintrc.json
@ -46,19 +57,23 @@ pub struct LintContext<'a> {
}
impl<'a> LintContext<'a> {
/// Base URL for the documentation, used to generate rule documentation URLs when a diagnostic is reported.
const WEBSITE_BASE_URL: &'static str = "https://oxc.rs/docs/guide/usage/linter/rules";
/// Set the plugin name for the current rule.
pub fn with_plugin_name(mut self, plugin: &'static str) -> Self {
self.current_plugin_name = plugin;
self.current_plugin_prefix = plugin_name_to_prefix(plugin);
self
}
/// Set the current rule name. Name should be kebab-cased like: `no-unused-vars` or `no-undef`.
pub fn with_rule_name(mut self, name: &'static str) -> Self {
self.current_rule_name = name;
self
}
/// Set the current rule fix capabilities. See [`RuleFixMeta`] for more information.
#[cfg(debug_assertions)]
pub fn with_rule_fix_capabilities(mut self, capabilities: RuleFixMeta) -> Self {
self.current_rule_fix_capabilities = capabilities;
@ -82,6 +97,7 @@ impl<'a> LintContext<'a> {
&self.parent.semantic
}
/// Get the control flow graph for the current program.
#[inline]
pub fn cfg(&self) -> &ControlFlowGraph {
// SAFETY: `LintContext::new` is the only way to construct a `LintContext` and we always
@ -89,6 +105,7 @@ impl<'a> LintContext<'a> {
unsafe { self.semantic().cfg().unwrap_unchecked() }
}
/// List of all disable directives in the file being linted.
#[inline]
pub fn disable_directives(&self) -> &DisableDirectives<'a> {
&self.parent.disable_directives
@ -124,6 +141,7 @@ impl<'a> LintContext<'a> {
&self.parent.config.settings
}
/// Sets of global variables that have been enabled or disabled.
#[inline]
pub fn globals(&self) -> &OxlintGlobals {
&self.parent.config.globals
@ -137,6 +155,12 @@ impl<'a> LintContext<'a> {
&self.parent.config.env
}
/// Checks if a given variable named is defined as a global variable in the current environment.
///
/// Example:
/// - `env_contains_var("Date")` returns `true` because it is a global builtin in all environments.
/// - `env_contains_var("HTMLElement")` returns `true` only if the `browser` environment is enabled.
/// - `env_contains_var("globalThis")` returns `true` only if the `es2020` environment or higher is enabled.
pub fn env_contains_var(&self, var: &str) -> bool {
if GLOBALS["builtin"].contains_key(var) {
return true;
@ -153,6 +177,8 @@ impl<'a> LintContext<'a> {
/* Diagnostics */
/// Add a diagnostic message to the list of diagnostics. Outputs a diagnostic with the current rule
/// name, severity, and a link to the rule's documentation URL.
fn add_diagnostic(&self, mut message: Message<'a>) {
if self.parent.disable_directives.contains(self.current_rule_name, message.span()) {
return;
@ -251,6 +277,12 @@ impl<'a> LintContext<'a> {
self.diagnostic_with_fix_of_kind(diagnostic, FixKind::DangerousFix, fix);
}
/// Report a lint rule violation and provide an automatic fix of a specific kind.
///
/// The second argument is a [closure] that takes a [`RuleFixer`] and
/// returns something that can turn into a [`RuleFix`].
///
/// [closure]: <https://doc.rust-lang.org/book/ch13-01-closures.html>
#[allow(clippy::missing_panics_doc)] // only panics in debug mode
pub fn diagnostic_with_fix_of_kind<C, F>(
&self,
@ -285,6 +317,7 @@ impl<'a> LintContext<'a> {
}
}
/// Framework flags, indicating front-end frameworks that might be in use.
pub fn frameworks(&self) -> FrameworkFlags {
self.parent.frameworks
}
@ -325,11 +358,19 @@ impl<'a> LintContext<'a> {
}
}
/// Gets the prefixed plugin name, given the short plugin name.
///
/// Example:
///
/// ```rust
/// assert_eq!(plugin_name_to_prefix("react"), "eslint-plugin-react");
/// ```
#[inline]
fn plugin_name_to_prefix(plugin_name: &'static str) -> &'static str {
PLUGIN_PREFIXES.get(plugin_name).copied().unwrap_or(plugin_name)
}
/// Map of plugin names to their prefixed versions.
const PLUGIN_PREFIXES: phf::Map<&'static str, &'static str> = phf::phf_map! {
"import" => "eslint-plugin-import",
"jest" => "eslint-plugin-jest",