fallow_core/plugins/

mod.rs

//! Plugin system for framework-aware codebase analysis.
//!
//! Unlike knip's JavaScript plugin system that evaluates config files at runtime,
//! fallow's plugin system uses Oxc's parser to extract configuration values from
//! JS/TS/JSON config files via AST walking, no JavaScript evaluation needed.
//!
//! Each plugin implements the [`Plugin`] trait with:
//! - **Static defaults**: Entry patterns, config file patterns, used exports
//! - **Dynamic resolution**: Parse tool config files to discover additional entries,
//!   referenced dependencies, and setup files

use std::path::{Path, PathBuf};

use fallow_config::{
    AutoImportRule, EntryPointRole, JsxImportSourceRule, PackageJson, UsedClassMemberRule,
};
use fallow_types::semantic::SemanticFrameworkContract;
use regex::Regex;

const TEST_ENTRY_POINT_PLUGINS: &[&str] = &[
    "ava",
    "bun",
    "deno",
    "cucumber",
    "cypress",
    "jest",
    "k6",
    "mocha",
    "playwright",
    "tap",
    "tsd",
    "vitest",
    "webdriverio",
];

const RUNTIME_ENTRY_POINT_PLUGINS: &[&str] = &[
    "adonis",
    "angular",
    "astro",
    "browser-extension",
    "convex",
    "docusaurus",
    "electron",
    "ember",
    "eve",
    "expo",
    "expo-router",
    "gatsby",
    "hardhat",
    "kibana",
    "module-federation",
    "nestjs",
    "next-intl",
    "nextjs",
    "nitro",
    "nuxt",
    "obsidian",
    "parcel",
    "qwik",
    "react-native",
    "react-router",
    "redwoodsdk",
    "remix",
    "rolldown",
    "rollup",
    "rsbuild",
    "rspack",
    "sanity",
    "supabase",
    "sveltekit",
    "tanstack-router",
    "tsdown",
    "tsup",
    "vercel",
    "vite",
    "vitepress",
    "waku",
    "webpack",
    "wrangler",
    "wxt",
];

#[cfg(test)]
const SUPPORT_ENTRY_POINT_PLUGINS: &[&str] = &[
    "content-collections",
    "contentlayer",
    "danger",
    "drizzle",
    "fumadocs",
    "i18next",
    "knex",
    "kysely",
    "mintlify",
    "msw",
    "opencode",
    "prisma",
    "storybook",
    "stryker",
    "typeorm",
    "velite",
];

/// Which workspace diagnostic kind a plugin-stage advisory becomes.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PluginConfigEffect {
    /// The plugin could not read the key in full, so part of what it declares
    /// never reached the analysis.
    Unreadable,
    /// The plugin read the key and does not model its effect, so a modeled
    /// default the run would otherwise have applied stood down.
    NotModeled,
}

/// One advisory about a config file a plugin read, before it becomes a
/// [`fallow_config::WorkspaceDiagnostic`].
///
/// A plugin knows the fact (which config file, which key, why) but not the root
/// the message renders against: in a workspace run its own `root` is the package
/// root, while the diagnostic's path and message are project-root-relative. The
/// conversion therefore happens once, where every plugin result has converged on
/// the project root, and `config_path` is kept ABSOLUTE until then so the
/// registry's canonical dedupe and the serialized root-relative form both work
/// from one value (issue #2736).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PluginConfigDiagnostic {
    /// Absolute path of the config file that was read.
    pub config_path: PathBuf,
    /// The plugin that read it, as it labels itself. Module Federation options
    /// reach four bundler plugins inline, and each names itself rather than the
    /// reader, because the config file the user must edit is the bundler's.
    pub plugin: String,
    /// The config key the advisory is about (`exposes`, `remotes`,
    /// `components`, `imports`).
    pub key: String,
    /// Why, as a kebab-case token from the resulting kind's open set.
    pub reason: String,
    /// Which workspace diagnostic kind this becomes.
    pub effect: PluginConfigEffect,
}

impl PluginConfigDiagnostic {
    /// Build an advisory about a key a plugin could not read in full.
    pub(super) fn unreadable(
        config_path: &Path,
        plugin: &str,
        key: &str,
        reason: &'static str,
    ) -> Self {
        Self {
            config_path: config_path.to_path_buf(),
            plugin: plugin.to_owned(),
            key: key.to_owned(),
            reason: reason.to_owned(),
            effect: PluginConfigEffect::Unreadable,
        }
    }

    /// Build an advisory about a key whose effect the plugin does not model.
    pub(crate) fn not_modeled(
        config_path: &Path,
        plugin: &str,
        key: &str,
        reason: &'static str,
    ) -> Self {
        Self {
            config_path: config_path.to_path_buf(),
            plugin: plugin.to_owned(),
            key: key.to_owned(),
            reason: reason.to_owned(),
            effect: PluginConfigEffect::NotModeled,
        }
    }

    /// Render this advisory against the PROJECT root, which is the root every
    /// consumer's paths are relative to.
    #[must_use]
    pub fn into_workspace_diagnostic(self, root: &Path) -> fallow_config::WorkspaceDiagnostic {
        let Self {
            config_path,
            plugin,
            key,
            reason,
            effect,
        } = self;
        let kind = match effect {
            PluginConfigEffect::Unreadable => {
                fallow_config::WorkspaceDiagnosticKind::PluginConfigUnreadable {
                    plugin,
                    key,
                    reason,
                }
            }
            PluginConfigEffect::NotModeled => {
                fallow_config::WorkspaceDiagnosticKind::PluginEffectNotModeled {
                    plugin,
                    key,
                    reason,
                }
            }
        };
        fallow_config::WorkspaceDiagnostic::new(root, config_path, kind)
    }
}

/// Result of resolving a plugin's config file.
#[derive(Debug, Default)]
pub struct PluginResult {
    /// Additional entry point glob patterns discovered from config.
    entry_patterns: Vec<PathRule>,
    /// When true, `entry_patterns` from config replace the plugin's static
    /// `entry_patterns()` defaults instead of adding to them. Tools like Vitest
    /// and Jest treat their config's include/testMatch as a replacement for built-in
    /// defaults, so when the config is explicit the static patterns must be dropped.
    replace_entry_patterns: bool,
    /// When true, a replacing config removes only the static defaults, and the
    /// replacing configs of one plugin run add their patterns together. When
    /// false, the last replacing config of the plugin wins.
    accumulate_config_entry_patterns: bool,
    /// When true, `used_exports` from config replace the plugin's static
    /// `used_export_rules()` defaults instead of adding to them.
    replace_used_export_rules: bool,
    /// Additional export-usage rules discovered from config.
    used_exports: Vec<UsedExportRule>,
    /// Class member rules that should never be flagged as unused. Contributed
    /// by plugins that know their framework invokes these methods at runtime
    /// and may scope suppression via `extends` / `implements` constraints when
    /// the method name is too common to allowlist globally.
    used_class_members: Vec<UsedClassMemberRule>,
    /// Dependencies referenced in config files (should not be flagged as unused).
    referenced_dependencies: Vec<String>,
    /// Dependencies a config credits only to the package that owns it, keyed
    /// by the path of that package's `package.json`.
    package_referenced_dependencies: Vec<(PathBuf, String)>,
    /// Additional files that are always considered used.
    always_used_files: Vec<String>,
    /// Path alias mappings discovered from config (prefix -> replacement directory).
    path_aliases: Vec<(String, String)>,
    /// Setup/helper files referenced from config.
    setup_files: Vec<PathBuf>,
    /// Test fixture glob patterns discovered from config.
    fixture_patterns: Vec<String>,
    /// Absolute directories to include when resolving SCSS/Sass `@import` and
    /// `@use` specifiers. Contributed by framework plugins that read their
    /// tool's equivalent of `includePaths` (e.g. Angular's
    /// `stylePreprocessorOptions.includePaths` from `angular.json` /
    /// `project.json`). Bare SCSS specifiers that fail to resolve relative to
    /// the importing file retry against each include path using the SCSS
    /// partial / directory-index conventions.
    scss_include_paths: Vec<PathBuf>,
    /// URL-to-filesystem static directory mappings discovered from tool config.
    /// Each tuple is `(absolute_source_dir, normalized_url_mount)`.
    static_dir_mappings: Vec<(PathBuf, String)>,
    framework_static_dir_mappings: Vec<(PathBuf, String)>,
    /// File-scoped dependency providers. Matching imports are considered
    /// available from the framework runtime and are not unlisted dependencies.
    provided_dependencies: Vec<ProvidedDependencyRule>,
    /// Advisories about the config file this result was read from. A plugin
    /// records the fact here instead of printing it, so it reaches the report
    /// and every consumer rather than only a stderr line.
    config_diagnostics: Vec<PluginConfigDiagnostic>,
    /// Where a Module Federation config exposes a file or declares a remote
    /// alias, kept so a trace can name the config (issue #2796).
    federation_sources: Vec<FederationSource>,
    /// JSX import sources that the config sets for the files it transforms.
    /// The resolver adds the runtime edge to each matching file without a
    /// JSX pragma.
    jsx_import_sources: Vec<JsxImportSourceRule>,
}

/// What a Module Federation config declares, and where, for the trace output.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct FederationSource {
    /// What the config names.
    pub target: FederationSourceTarget,
    /// The absolute path of the config file.
    pub config_path: PathBuf,
    /// The plugin that read the config, as it labels itself.
    pub plugin: String,
    /// The config key that names the target.
    pub key: &'static str,
}

/// The thing a [`FederationSource`] names.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum FederationSourceTarget {
    /// An `exposes` target, as the entry-point rule it became.
    Exposed(PathRule),
    /// A `remotes` alias.
    Remote(String),
}

impl FederationSource {
    #[must_use]
    fn prefixed(&self, ws_prefix: &str) -> Self {
        let target = match &self.target {
            FederationSourceTarget::Exposed(rule) => {
                FederationSourceTarget::Exposed(rule.prefixed(ws_prefix))
            }
            FederationSourceTarget::Remote(alias) => FederationSourceTarget::Remote(alias.clone()),
        };
        Self {
            target,
            config_path: self.config_path.clone(),
            plugin: self.plugin.clone(),
            key: self.key,
        }
    }
}

/// Match the Module Federation sources of one analysis against the discovered
/// files, for the trace output.
///
/// Only a project with a Federation config pays for the match, and it runs
/// once per analysis, so a trace reads plain data. A remote that a literal
/// runtime call (`registerRemotes`, `loadRemote`, `init`, `createInstance`) names traces to the source
/// file, with the function name as the key.
#[must_use]
pub fn federation_trace_provenance(
    root: &Path,
    files: &[crate::discover::DiscoveredFile],
    sources: &[FederationSource],
    modules: &[crate::extract::ModuleInfo],
) -> fallow_types::trace::TraceProvenance {
    let mut provenance = fallow_types::trace::TraceProvenance::default();
    push_runtime_remote_sources(&mut provenance, root, files, modules);
    if sources.is_empty() {
        return provenance;
    }
    let mut exposed = Vec::new();
    for source in sources {
        let config = source
            .config_path
            .strip_prefix(root)
            .unwrap_or(&source.config_path)
            .to_path_buf();
        let trace_source = fallow_types::trace::TraceSource {
            kind: "module-federation".to_owned(),
            plugin: source.plugin.clone(),
            config,
            key: source.key.to_owned(),
        };
        match &source.target {
            FederationSourceTarget::Exposed(rule) => {
                if let Some(compiled) =
                    CompiledPathRule::for_entry_rule(rule, "Module Federation exposes target")
                {
                    exposed.push((compiled, trace_source));
                }
            }
            FederationSourceTarget::Remote(alias) => {
                provenance.push_dependency(alias.clone(), trace_source);
            }
        }
    }
    if exposed.is_empty() {
        return provenance;
    }
    for file in files {
        let Ok(relative) = file.path.strip_prefix(root) else {
            continue;
        };
        let relative_str = relative.to_string_lossy().replace('\\', "/");
        for (rule, source) in &exposed {
            if rule.matches(&relative_str) {
                provenance.push_file(relative.to_path_buf(), source.clone());
            }
        }
    }
    provenance
}

/// Record why the unused devDependency check credits each plugin tooling
/// dependency, so `--trace-dependency` explains the credit instead of calling
/// the dependency unused.
pub fn push_tooling_trace_credits(
    provenance: &mut fallow_types::trace::TraceProvenance,
    root: &Path,
    workspaces: &[fallow_config::WorkspaceInfo],
    plugin_result: &AggregatedPluginResult,
) {
    for entry in &plugin_result.plugin_tooling {
        let Some(evidence) = entry.evidence(&plugin_result.script_used_packages) else {
            continue;
        };
        let credit = match evidence {
            PluginToolingEvidence::OwnConfig(config) => fallow_types::trace::ToolingCredit {
                reason: "plugin-config".to_owned(),
                plugin: Some(entry.plugin.clone()),
                config: Some(config.strip_prefix(root).unwrap_or(config).to_path_buf()),
                reference: None,
            },
            PluginToolingEvidence::Reference(name) => fallow_types::trace::ToolingCredit {
                reason: "plugin-reference".to_owned(),
                plugin: Some(entry.plugin.clone()),
                config: None,
                reference: Some(name.to_owned()),
            },
        };
        for dependency in &entry.dependencies {
            provenance.push_tooling_credit(dependency.clone(), credit.clone());
        }
    }
    push_types_trace_credits(provenance, plugin_result);
    push_catalogue_trace_credits(provenance, root, workspaces, plugin_result);
}

/// Record why the unused devDependency check credits each catalogue entry in
/// `devDependencies` that the trace would otherwise call unused: a library
/// entry by name, a command-line tool by its own config file or its
/// package.json key, and any entry that the same manifest lists in
/// `peerDependencies`.
///
/// The check reads each declaring manifest on its own, so a credit here comes
/// from a manifest that declares the name. A config in a sibling workspace
/// gives no credit.
fn push_catalogue_trace_credits(
    provenance: &mut fallow_types::trace::TraceProvenance,
    root: &Path,
    workspaces: &[fallow_config::WorkspaceInfo],
    plugin_result: &AggregatedPluginResult,
) {
    let manifests = read_trace_manifests(root, workspaces);
    let mut names: Vec<&String> = plugin_result.dev_dependency_names.iter().collect();
    names.sort_unstable();
    for name in names {
        let declaring: Vec<&(PathBuf, serde_json::Value)> = manifests
            .iter()
            .filter(|(_, manifest)| manifest_lists(manifest, "devDependencies", name))
            .collect();
        if let Some(credit) = catalogue_credit(name, root, &declaring) {
            provenance.push_tooling_credit(name.clone(), credit);
        }
        if let Some((path, _)) = declaring
            .iter()
            .find(|(_, manifest)| manifest_lists(manifest, "peerDependencies", name))
        {
            provenance.push_tooling_credit(
                name.clone(),
                fallow_types::trace::ToolingCredit {
                    reason: "own-peer".to_owned(),
                    plugin: None,
                    config: Some(path.strip_prefix(root).unwrap_or(path).to_path_buf()),
                    reference: None,
                },
            );
        }
    }
}

/// The root manifest and each workspace manifest, parsed, root first.
fn read_trace_manifests(
    root: &Path,
    workspaces: &[fallow_config::WorkspaceInfo],
) -> Vec<(PathBuf, serde_json::Value)> {
    std::iter::once(root)
        .chain(
            workspaces
                .iter()
                .map(|ws| ws.root.as_path())
                .filter(|ws_root| *ws_root != root),
        )
        .filter_map(|package_root| {
            let path = package_root.join("package.json");
            let content = std::fs::read_to_string(&path).ok()?;
            serde_json::from_str(&content)
                .ok()
                .map(|value| (path, value))
        })
        .collect()
}

fn manifest_lists(manifest: &serde_json::Value, section: &str, name: &str) -> bool {
    manifest
        .get(section)
        .and_then(serde_json::Value::as_object)
        .is_some_and(|deps| deps.contains_key(name))
}

/// The catalogue credit of `name` from the first declaring manifest that the
/// unused devDependency check credits.
fn catalogue_credit(
    name: &str,
    root: &Path,
    declaring: &[&(PathBuf, serde_json::Value)],
) -> Option<fallow_types::trace::ToolingCredit> {
    if is_ambient_types_package(name) || types_package_target(name).is_some() {
        return None;
    }
    let Some(patterns) = cli_tooling_config_patterns(name) else {
        return is_known_tooling_dependency(name).then(|| fallow_types::trace::ToolingCredit {
            reason: "known-tooling".to_owned(),
            plugin: None,
            config: None,
            reference: None,
        });
    };
    let config = declaring.iter().find_map(|(path, manifest)| {
        crate::analyze::cli_tool_own_config(name, patterns, root, path, Some(manifest))
    })?;
    Some(fallow_types::trace::ToolingCredit {
        reason: "known-tooling-config".to_owned(),
        plugin: None,
        config: Some(config.strip_prefix(root).unwrap_or(&config).to_path_buf()),
        reference: None,
    })
}

/// Record why the unused devDependency check credits each type package in
/// `devDependencies`: ambient globals, a declared target package, or a
/// tsconfig `types` entry. A target that the code imports is credited by the trace
/// itself, which reads the module graph.
fn push_types_trace_credits(
    provenance: &mut fallow_types::trace::TraceProvenance,
    plugin_result: &AggregatedPluginResult,
) {
    let declared = plugin_result.dependency_binaries.declared_packages();
    let mut names: Vec<&String> = plugin_result.dev_dependency_names.iter().collect();
    names.sort_unstable();
    for name in names {
        let credit = if is_ambient_types_package(name) {
            fallow_types::trace::ToolingCredit {
                reason: "ambient-types".to_owned(),
                plugin: None,
                config: None,
                reference: None,
            }
        } else if let Some(target) = types_package_target(name) {
            if declared.contains(&target) {
                fallow_types::trace::ToolingCredit {
                    reason: "types-target".to_owned(),
                    plugin: None,
                    config: None,
                    reference: Some(target),
                }
            } else if plugin_result.referenced_dependencies.contains(name) {
                fallow_types::trace::ToolingCredit {
                    reason: "types-config".to_owned(),
                    plugin: None,
                    config: None,
                    reference: None,
                }
            } else {
                continue;
            }
        } else {
            continue;
        };
        provenance.push_tooling_credit(name.clone(), credit);
    }
}

/// Add a trace source for each remote that a literal runtime call names.
fn push_runtime_remote_sources(
    provenance: &mut fallow_types::trace::TraceProvenance,
    root: &Path,
    files: &[crate::discover::DiscoveredFile],
    modules: &[crate::extract::ModuleInfo],
) {
    for module in modules {
        let mut file = None;
        for fact in module.semantic_facts.iter() {
            let fallow_types::extract::SemanticFact::FederationRuntimeRemote(fact) = fact else {
                continue;
            };
            let Some(remote) = &fact.remote else {
                continue;
            };
            let Some(path) = file.get_or_insert_with(|| {
                files.get(module.file_id.0 as usize).map(|file| {
                    file.path
                        .strip_prefix(root)
                        .unwrap_or(&file.path)
                        .to_path_buf()
                })
            }) else {
                break;
            };
            provenance.push_dependency(
                remote.clone(),
                fallow_types::trace::TraceSource {
                    kind: "module-federation".to_owned(),
                    plugin: "module-federation".to_owned(),
                    config: path.clone(),
                    key: fact.call.name().to_owned(),
                },
            );
        }
    }
}

impl PluginResult {
    /// Register `entry` values that a bundler reads relative to the directory
    /// of its config file. The project root run and the workspace run can read
    /// the same config, so each value is anchored at the config directory. A
    /// value with a leading `!` excludes its matches from every other value.
    fn extend_config_dir_entry_patterns(
        &mut self,
        values: Vec<String>,
        config_path: &Path,
        root: &Path,
    ) {
        let (negated, positive): (Vec<String>, Vec<String>) =
            values.into_iter().partition(|value| value.starts_with('!'));
        let excluded: Vec<String> = negated
            .iter()
            .filter_map(|value| value.strip_prefix('!'))
            .filter_map(|value| config_parser::normalize_config_path(value, config_path, root))
            .collect();
        self.entry_patterns.extend(
            positive
                .iter()
                .filter_map(|value| config_parser::normalize_config_path(value, config_path, root))
                .map(|pattern| {
                    PathRule::new(pattern).with_excluded_globs(excluded.iter().cloned())
                }),
        );
    }

    /// Register an entry pattern whose leading `../` segments are relative to
    /// the plugin root. The workspace prefix resolves them.
    fn push_parent_relative_entry_pattern(&mut self, pattern: String) {
        let mut rule = PathRule::new(pattern);
        rule.parent_relative = true;
        self.entry_patterns.push(rule);
    }

    fn push_entry_pattern(&mut self, pattern: impl Into<String>) {
        self.entry_patterns
            .push(PathRule::new(normalize_entry_pattern(pattern.into())));
    }

    fn extend_entry_patterns<I, S>(&mut self, patterns: I)
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.entry_patterns.extend(
            patterns
                .into_iter()
                .map(|pat| PathRule::new(normalize_entry_pattern(pat.into()))),
        );
    }

    /// Route each config value to the surface that can use it: a value naming a
    /// module request credits its package, every other value becomes an entry
    /// pattern.
    ///
    /// A bundler `entry` accepts a project file and a bare module request such as
    /// `react-hot-loader/patch` in the same list. A module request names no file,
    /// so a glob built from it matches nothing while the package still needs
    /// dependency credit. Module Federation `exposes` targets already split the
    /// two this way (issue #2706); bundler entries now do too (issue #2739).
    ///
    /// `resolve_path` maps a path value to its project-relative form, for
    /// example against a `context` directory. It runs after the value is
    /// classified, because a joined path such as `app/main` no longer carries
    /// the `./` that marks it as a path.
    fn extend_entry_patterns_or_dependencies<I, S>(
        &mut self,
        values: I,
        resolve_path: impl Fn(String) -> String,
    ) where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        for value in values {
            let value = value.into();
            if let Some(request) = module_request(&value) {
                self.referenced_dependencies
                    .push(crate::resolve::extract_package_name(request));
                continue;
            }
            self.push_entry_path(resolve_path(value));
        }
    }

    /// Route each value of a rollup-style `input` to both surfaces when it is
    /// ambiguous.
    ///
    /// Rollup, rolldown and vite resolve an `input` value with no importer: a
    /// resolve plugin can read it as a module request, and without one it is a
    /// path relative to the working directory. A value without `./`, `../` or
    /// `/`, without a source extension and without glob syntax can therefore
    /// name either one. It keeps the entry pattern, and it credits the package
    /// unless the value names a file under `root`. A value that names a
    /// project file is a path, so it must not hide an unused package that has
    /// the same first segment (issue #2753).
    fn extend_entry_patterns_and_dependencies<I, S>(&mut self, values: I, root: &Path)
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        for value in values {
            let value = value.into();
            if let Some(request) = module_request(&value)
                && !names_project_file(root, request)
            {
                self.referenced_dependencies
                    .push(crate::resolve::extract_package_name(request));
            }
            self.push_entry_path(value);
        }
    }

    /// Register each value as a bundler entry path.
    fn extend_entry_paths<I, S>(&mut self, values: I)
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        for value in values {
            self.push_entry_path(value.into());
        }
    }

    /// Register a bundler entry path.
    ///
    /// A bundler resolves an entry without a source extension the way it
    /// resolves an import: first as a file with each extension, then as a
    /// directory through its index file. `./lib` therefore names
    /// `lib/index.ts`, and `./src/app` names `src/app.ts`. The value as written
    /// stays a pattern too, so a file without an extension still matches.
    fn push_entry_path(&mut self, value: String) {
        if has_glob_syntax(&value) || has_source_extension(&value) {
            self.push_entry_pattern(value);
            return;
        }
        let base = value.trim_end_matches('/').to_owned();
        self.push_entry_pattern(value);
        self.push_entry_pattern(format!("{base}.{REQUEST_EXTENSIONS}"));
        self.push_entry_pattern(format!("{base}/index.{REQUEST_EXTENSIONS}"));
    }

    fn push_used_export_rule(
        &mut self,
        pattern: impl Into<String>,
        exports: impl IntoIterator<Item = impl Into<String>>,
    ) {
        self.used_exports
            .push(UsedExportRule::new(pattern, exports));
    }

    /// Whether this result contributes nothing, which lets the registry skip a
    /// config file entirely.
    ///
    /// A config that yields only a diagnostic is NOT empty: an unreadable
    /// `exposes` in a config that declares nothing else is exactly the case the
    /// advisory exists for, and skipping the result would drop it.
    #[must_use]
    const fn is_empty(&self) -> bool {
        self.config_diagnostics.is_empty()
            && self.entry_patterns.is_empty()
            && self.used_exports.is_empty()
            && self.used_class_members.is_empty()
            && self.referenced_dependencies.is_empty()
            && self.package_referenced_dependencies.is_empty()
            && self.always_used_files.is_empty()
            && self.path_aliases.is_empty()
            && self.setup_files.is_empty()
            && self.fixture_patterns.is_empty()
            && self.scss_include_paths.is_empty()
            && self.static_dir_mappings.is_empty()
            && self.framework_static_dir_mappings.is_empty()
            && self.provided_dependencies.is_empty()
            && self.federation_sources.is_empty()
            && self.jsx_import_sources.is_empty()
    }
}

/// Whether an extensionless value names a file under `root`: the value itself,
/// the value with a source extension, or the index file of the directory it
/// names. This is the order in which a bundler resolves a path.
fn names_project_file(root: &Path, value: &str) -> bool {
    let base = root.join(value);
    base.is_file()
        || crate::discover::SOURCE_EXTENSIONS.iter().any(|extension| {
            let mut candidate = base.clone().into_os_string();
            candidate.push(".");
            candidate.push(extension);
            Path::new(&candidate).is_file() || base.join(format!("index.{extension}")).is_file()
        })
}

/// Brace list of the extensions a bundler tries for a request that names no
/// extension. Entry patterns are plain globs with no extension expansion, so a
/// bare `src/Button` would match no file.
const REQUEST_EXTENSIONS: &str = "{ts,tsx,mts,cts,gts,js,jsx,mjs,cjs,gjs,vue,svelte,astro,mdx}";

fn normalize_entry_pattern(pattern: String) -> String {
    pattern
        .strip_prefix("./")
        .map(str::to_owned)
        .unwrap_or(pattern)
}

/// The module request a config value names, or `None` when the value names a
/// file or a pattern over project files.
///
/// A bundler resolves a value without a leading `./`, `../` or `/` and without a
/// source extension through module resolution, so it names a package. Both
/// Module Federation `exposes` targets and bundler `entry` values are read this
/// way. A value carrying glob syntax is a path in every case: no module
/// resolution accepts a glob, so `src/pages/**` stays an entry pattern. A
/// resource query is not part of the request, so it is dropped before both
/// tests and before the package name is taken.
fn module_request(value: &str) -> Option<&str> {
    let request = strip_resource_query(value);
    (config_parser::is_package_specifier(request)
        && !has_glob_syntax(request)
        && !has_source_extension(request))
    .then_some(request)
}

/// Drop a trailing resource query from a config value.
///
/// A bundler hands everything after the first `?` to the loader, so the standard
/// hot-reload entry `webpack-hot-middleware/client?reload=true` names the
/// package's `client` module. A `?` is also the single-character glob wildcard,
/// so what follows it decides: `reload=true` is a query, the `.ts` of
/// `src/pag?.ts` is not.
fn strip_resource_query(value: &str) -> &str {
    match value.split_once('?') {
        Some((request, query)) if is_resource_query(query) => request,
        _ => value,
    }
}

/// Whether a string is an `&`-separated list of `key` or `key=value` pairs whose
/// keys read like identifiers.
fn is_resource_query(query: &str) -> bool {
    !query.is_empty()
        && query.split('&').all(|pair| {
            let key = pair.split_once('=').map_or(pair, |(key, _)| key);
            key.starts_with(|first: char| first.is_ascii_alphanumeric() || first == '_')
                && key
                    .chars()
                    .all(|char| char.is_ascii_alphanumeric() || matches!(char, '_' | '-' | '.'))
        })
}

/// Whether a config value carries glob metacharacters, which makes it a pattern
/// over project files rather than a single path or module request.
fn has_glob_syntax(value: &str) -> bool {
    value.contains('*') || value.contains('?') || value.contains('[') || value.contains('{')
}

/// Whether a config value carries an extension discovery analyzes. Discovery's
/// own extension set decides, so a value naming a file type discovery does not
/// analyze stays a module request.
fn has_source_extension(value: &str) -> bool {
    Path::new(value)
        .extension()
        .and_then(|ext| ext.to_str())
        .is_some_and(|ext| {
            crate::discover::SOURCE_EXTENSIONS.contains(&ext.to_ascii_lowercase().as_str())
        })
}

/// A file-pattern rule with optional exclusion globs plus path-level or
/// segment-level regex filters.
///
/// Exclusion regexes are matched against the project-relative path and should be
/// anchored when generated dynamically so they can be safely workspace-prefixed.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct PathRule {
    pub pattern: String,
    pub exclude_globs: Vec<String>,
    pub exclude_regexes: Vec<String>,
    /// Regexes matched against individual path segments. These are not prefixed
    /// for workspaces because they intentionally operate on segment names rather
    /// than the full project-relative path.
    pub exclude_segment_regexes: Vec<String>,
    /// Whether the leading `../` segments of `pattern` are relative to the
    /// plugin root, so the workspace prefix resolves them. Only the Module
    /// Federation reader sets it, for an `exposes` target in a sibling
    /// workspace. Other plugins emit patterns relative to a config directory,
    /// such as the Storybook `../src/**`, which must not climb out of the
    /// workspace.
    pub parent_relative: bool,
}

impl PathRule {
    #[must_use]
    pub(crate) fn new(pattern: impl Into<String>) -> Self {
        Self {
            pattern: pattern.into(),
            exclude_globs: Vec::new(),
            exclude_regexes: Vec::new(),
            exclude_segment_regexes: Vec::new(),
            parent_relative: false,
        }
    }

    #[must_use]
    fn from_static(pattern: &'static str) -> Self {
        Self::new(pattern)
    }

    #[must_use]
    pub(crate) fn with_excluded_globs<I, S>(mut self, patterns: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.exclude_globs
            .extend(patterns.into_iter().map(Into::into));
        self
    }

    #[must_use]
    fn with_excluded_regexes<I, S>(mut self, patterns: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.exclude_regexes
            .extend(patterns.into_iter().map(Into::into));
        self
    }

    #[must_use]
    fn with_excluded_segment_regexes<I, S>(mut self, patterns: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.exclude_segment_regexes
            .extend(patterns.into_iter().map(Into::into));
        self
    }

    #[must_use]
    fn prefixed(&self, ws_prefix: &str) -> Self {
        let pattern = if self.parent_relative && self.pattern.starts_with("../") {
            resolve_parent_relative_pattern(&self.pattern, ws_prefix)
        } else {
            prefix_workspace_pattern(&self.pattern, ws_prefix)
        };
        Self {
            pattern,
            exclude_globs: self
                .exclude_globs
                .iter()
                .map(|pattern| prefix_workspace_pattern(pattern, ws_prefix))
                .collect(),
            exclude_regexes: self
                .exclude_regexes
                .iter()
                .map(|pattern| prefix_workspace_regex(pattern, ws_prefix))
                .collect(),
            exclude_segment_regexes: self.exclude_segment_regexes.clone(),
            parent_relative: false,
        }
    }
}

/// A used-export rule bound to a file-pattern rule.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct UsedExportRule {
    pub(crate) path: PathRule,
    pub(crate) exports: Vec<String>,
}

impl UsedExportRule {
    #[must_use]
    pub(crate) fn new(
        pattern: impl Into<String>,
        exports: impl IntoIterator<Item = impl Into<String>>,
    ) -> Self {
        Self {
            path: PathRule::new(pattern),
            exports: exports.into_iter().map(Into::into).collect(),
        }
    }

    #[must_use]
    fn from_static(pattern: &'static str, exports: &'static [&'static str]) -> Self {
        Self::new(pattern, exports.iter().copied())
    }

    #[must_use]
    fn with_excluded_globs<I, S>(mut self, patterns: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.path = self.path.with_excluded_globs(patterns);
        self
    }

    #[must_use]
    fn with_excluded_regexes<I, S>(mut self, patterns: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.path = self.path.with_excluded_regexes(patterns);
        self
    }

    #[must_use]
    fn with_excluded_segment_regexes<I, S>(mut self, patterns: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: Into<String>,
    {
        self.path = self.path.with_excluded_segment_regexes(patterns);
        self
    }

    #[must_use]
    fn prefixed(&self, ws_prefix: &str) -> Self {
        Self {
            path: self.path.prefixed(ws_prefix),
            exports: self.exports.clone(),
        }
    }
}

/// A used-export rule tagged with the plugin that contributed it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct PluginUsedExportRule {
    pub(crate) plugin_name: String,
    pub(crate) rule: UsedExportRule,
}

impl PluginUsedExportRule {
    #[must_use]
    pub(crate) fn new(plugin_name: impl Into<String>, rule: UsedExportRule) -> Self {
        Self {
            plugin_name: plugin_name.into(),
            rule,
        }
    }

    #[must_use]
    fn prefixed(&self, ws_prefix: &str) -> Self {
        Self {
            plugin_name: self.plugin_name.clone(),
            rule: self.rule.prefixed(ws_prefix),
        }
    }
}

/// A file-scoped dependency provider rule contributed by a framework plugin.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct ProvidedDependencyRule {
    pub(crate) path: PathRule,
    exact_specifiers: Vec<String>,
    specifier_prefixes: Vec<String>,
}

impl ProvidedDependencyRule {
    #[must_use]
    fn new(
        pattern: impl Into<String>,
        exact_specifiers: impl IntoIterator<Item = impl Into<String>>,
        specifier_prefixes: impl IntoIterator<Item = impl Into<String>>,
    ) -> Self {
        Self {
            path: PathRule::new(pattern),
            exact_specifiers: exact_specifiers.into_iter().map(Into::into).collect(),
            specifier_prefixes: specifier_prefixes.into_iter().map(Into::into).collect(),
        }
    }

    #[must_use]
    fn prefixed(&self, ws_prefix: &str) -> Self {
        Self {
            path: self.path.prefixed(ws_prefix),
            exact_specifiers: self.exact_specifiers.clone(),
            specifier_prefixes: self.specifier_prefixes.clone(),
        }
    }

    #[must_use]
    pub(crate) fn may_cover_package(&self, package_name: &str) -> bool {
        self.exact_specifiers
            .iter()
            .chain(self.specifier_prefixes.iter())
            .any(|specifier| crate::resolve::extract_package_name(specifier) == package_name)
    }

    #[must_use]
    pub(crate) fn covers_specifier(&self, specifier: &str) -> bool {
        self.exact_specifiers
            .iter()
            .any(|allowed| allowed == specifier)
            || self
                .specifier_prefixes
                .iter()
                .any(|prefix| specifier.starts_with(prefix))
    }
}

/// A compiled path rule matcher shared by entry-point and used-export matching.
#[derive(Debug, Clone)]
pub(crate) struct CompiledPathRule {
    include: globset::GlobMatcher,
    exclude_globs: Vec<globset::GlobMatcher>,
    exclude_regexes: Vec<Regex>,
    exclude_segment_regexes: Vec<Regex>,
}

impl CompiledPathRule {
    pub(crate) fn for_entry_rule(rule: &PathRule, rule_kind: &str) -> Option<Self> {
        let include = match globset::GlobBuilder::new(&rule.pattern)
            .literal_separator(true)
            .build()
        {
            Ok(glob) => glob.compile_matcher(),
            Err(err) => {
                tracing::warn!("invalid {rule_kind} '{}': {err}", rule.pattern);
                return None;
            }
        };
        Some(Self {
            include,
            exclude_globs: compile_excluded_globs(&rule.exclude_globs, rule_kind, &rule.pattern),
            exclude_regexes: compile_excluded_regexes(
                &rule.exclude_regexes,
                rule_kind,
                &rule.pattern,
            ),
            exclude_segment_regexes: compile_excluded_segment_regexes(
                &rule.exclude_segment_regexes,
                rule_kind,
                &rule.pattern,
            ),
        })
    }

    pub(crate) fn for_used_export_rule(rule: &PathRule, rule_kind: &str) -> Option<Self> {
        let include = match globset::Glob::new(&rule.pattern) {
            Ok(glob) => glob.compile_matcher(),
            Err(err) => {
                tracing::warn!("invalid {rule_kind} '{}': {err}", rule.pattern);
                return None;
            }
        };
        Some(Self {
            include,
            exclude_globs: compile_excluded_globs(&rule.exclude_globs, rule_kind, &rule.pattern),
            exclude_regexes: compile_excluded_regexes(
                &rule.exclude_regexes,
                rule_kind,
                &rule.pattern,
            ),
            exclude_segment_regexes: compile_excluded_segment_regexes(
                &rule.exclude_segment_regexes,
                rule_kind,
                &rule.pattern,
            ),
        })
    }

    #[must_use]
    pub(crate) fn matches(&self, path: &str) -> bool {
        self.include.is_match(path)
            && !self.exclude_globs.iter().any(|glob| glob.is_match(path))
            && !self
                .exclude_regexes
                .iter()
                .any(|regex| regex.is_match(path))
            && !matches_segment_regex(path, &self.exclude_segment_regexes)
    }
}

fn prefix_workspace_pattern(pattern: &str, ws_prefix: &str) -> String {
    if pattern.starts_with(ws_prefix) || pattern.starts_with('/') {
        pattern.to_string()
    } else {
        format!("{ws_prefix}/{pattern}")
    }
}

/// Resolve the leading `../` segments of a parent-relative pattern against the
/// workspace prefix, so a pattern that names a file in a sibling workspace
/// matches from the project root. A pattern that climbs past the project root,
/// or a prefix that is not project-relative, keeps the pattern as written,
/// which matches no project file.
fn resolve_parent_relative_pattern(pattern: &str, ws_prefix: &str) -> String {
    if ws_prefix.starts_with('/') || Path::new(ws_prefix).is_absolute() {
        return pattern.to_string();
    }
    // The workspace prefix comes from a native path, so on Windows its
    // segments are separated by backslashes.
    let mut base: Vec<&str> = ws_prefix
        .split(['/', '\\'])
        .filter(|segment| !segment.is_empty())
        .collect();
    let mut rest = pattern;
    while let Some(stripped) = rest.strip_prefix("../") {
        if base.pop().is_none() {
            return pattern.to_string();
        }
        rest = stripped;
    }
    if base.is_empty() {
        rest.to_string()
    } else {
        format!("{}/{rest}", base.join("/"))
    }
}

fn prefix_workspace_regex(pattern: &str, ws_prefix: &str) -> String {
    if let Some(pattern) = pattern.strip_prefix('^') {
        format!("^{}/{}", regex::escape(ws_prefix), pattern)
    } else {
        format!("^{}/(?:{})", regex::escape(ws_prefix), pattern)
    }
}

fn compile_excluded_globs(
    patterns: &[String],
    rule_kind: &str,
    rule_pattern: &str,
) -> Vec<globset::GlobMatcher> {
    patterns
        .iter()
        .filter_map(|pattern| {
            match globset::GlobBuilder::new(pattern)
                .literal_separator(true)
                .build()
            {
                Ok(glob) => Some(glob.compile_matcher()),
                Err(err) => {
                    tracing::warn!(
                        "skipping invalid excluded glob '{}' for {} '{}': {err}",
                        pattern,
                        rule_kind,
                        rule_pattern
                    );
                    None
                }
            }
        })
        .collect()
}

fn compile_excluded_regexes(
    patterns: &[String],
    rule_kind: &str,
    rule_pattern: &str,
) -> Vec<Regex> {
    patterns
        .iter()
        .filter_map(|pattern| match Regex::new(pattern) {
            Ok(regex) => Some(regex),
            Err(err) => {
                tracing::warn!(
                    "skipping invalid excluded regex '{}' for {} '{}': {err}",
                    pattern,
                    rule_kind,
                    rule_pattern
                );
                None
            }
        })
        .collect()
}

fn compile_excluded_segment_regexes(
    patterns: &[String],
    rule_kind: &str,
    rule_pattern: &str,
) -> Vec<Regex> {
    patterns
        .iter()
        .filter_map(|pattern| match Regex::new(pattern) {
            Ok(regex) => Some(regex),
            Err(err) => {
                tracing::warn!(
                    "skipping invalid excluded segment regex '{}' for {} '{}': {err}",
                    pattern,
                    rule_kind,
                    rule_pattern
                );
                None
            }
        })
        .collect()
}

/// Whether a segment of `path` matches one of `regexes`. The path can use the
/// native separator: on Windows a caller can pass `src\pages\x.tsx`.
fn matches_segment_regex(path: &str, regexes: &[Regex]) -> bool {
    path.split(std::path::is_separator)
        .any(|segment| regexes.iter().any(|regex| regex.is_match(segment)))
}

impl From<String> for PathRule {
    fn from(pattern: String) -> Self {
        Self::new(pattern)
    }
}

impl From<&str> for PathRule {
    fn from(pattern: &str) -> Self {
        Self::new(pattern)
    }
}

impl std::ops::Deref for PathRule {
    type Target = str;

    fn deref(&self) -> &Self::Target {
        &self.pattern
    }
}

impl PartialEq<&str> for PathRule {
    fn eq(&self, other: &&str) -> bool {
        self.pattern == *other
    }
}

impl PartialEq<str> for PathRule {
    fn eq(&self, other: &str) -> bool {
        self.pattern == other
    }
}

impl PartialEq<String> for PathRule {
    fn eq(&self, other: &String) -> bool {
        &self.pattern == other
    }
}

/// A framework/tool plugin that contributes to dead code analysis.
pub trait Plugin: Send + Sync {
    /// Human-readable plugin name.
    fn name(&self) -> &'static str;

    /// Package names that activate this plugin when found in package.json.
    /// Supports exact matches and prefix patterns (ending with `/`).
    fn enablers(&self) -> &'static [&'static str] {
        &[]
    }

    /// Check if this plugin should be active for the given project.
    /// Default implementation checks `enablers()` against package.json dependencies.
    fn is_enabled(&self, pkg: &PackageJson, root: &Path) -> bool {
        let deps = pkg.all_dependency_names();
        self.is_enabled_with_deps(&deps, root)
    }

    /// Fast variant of `is_enabled` that accepts a pre-computed deps list.
    /// Avoids repeated `all_dependency_names()` allocation when checking many plugins.
    fn is_enabled_with_deps(&self, deps: &[String], _root: &Path) -> bool {
        let enablers = self.enablers();
        if enablers.is_empty() {
            return false;
        }
        enablers.iter().any(|enabler| {
            if enabler.ends_with('/') {
                // Prefix match (e.g., "@storybook/" matches "@storybook/react")
                deps.iter().any(|d| d.starts_with(enabler))
            } else {
                deps.iter().any(|d| d == enabler)
            }
        })
    }

    /// Check whether this plugin should be active with source discovery available.
    ///
    /// Most plugins only need dependency/config activation. Convention-only tools
    /// can override this to activate from discovered source filenames without
    /// forcing a separate filesystem walk.
    ///
    /// `candidate_index` is the discovery walk's in-memory listing of source +
    /// non-source config-candidate files (`Some` outside production mode, `None`
    /// in production). A plugin that activates on a non-source sentinel file
    /// (`manifest.json`, `.env.schema`) can consult it to avoid a per-directory
    /// filesystem probe; when it is `None`, the plugin falls back to the
    /// filesystem.
    fn is_enabled_with_files(
        &self,
        deps: &[String],
        root: &Path,
        _discovered_files: &[PathBuf],
        _candidate_index: Option<&registry::ConfigCandidateIndex>,
    ) -> bool {
        self.is_enabled_with_deps(deps, root)
    }

    /// Package-script binary/package names that can activate this plugin.
    fn script_enablers(&self) -> &'static [&'static str] {
        &[]
    }

    /// Check whether this plugin should be active from package.json scripts.
    fn is_enabled_with_scripts(
        &self,
        script_packages: &rustc_hash::FxHashSet<String>,
        _root: &Path,
    ) -> bool {
        let enablers = self.script_enablers();
        if enablers.is_empty() {
            return false;
        }
        enablers.iter().any(|enabler| {
            if enabler.ends_with('/') {
                script_packages
                    .iter()
                    .any(|package| package.starts_with(enabler))
            } else {
                script_packages.contains(*enabler)
            }
        })
    }

    /// Default glob patterns for entry point files.
    fn entry_patterns(&self) -> &'static [&'static str] {
        &[]
    }

    /// Entry point rules with optional exclusions.
    fn entry_pattern_rules(&self) -> Vec<PathRule> {
        self.entry_patterns()
            .iter()
            .map(|pattern| PathRule::from_static(pattern))
            .collect()
    }

    /// How this plugin's entry patterns should contribute to coverage reachability.
    ///
    /// `Support` roots keep files alive for dead-code analysis but do not count
    /// as runtime or test reachability for static coverage gaps.
    fn entry_point_role(&self) -> EntryPointRole {
        builtin_entry_point_role(self.name())
    }

    /// Glob patterns for config files this plugin can parse.
    fn config_patterns(&self) -> &'static [&'static str] {
        &[]
    }

    /// Files that are always considered "used" when this plugin is active.
    fn always_used(&self) -> &'static [&'static str] {
        &[]
    }

    /// Exports that are always considered used for matching file patterns.
    fn used_exports(&self) -> Vec<(&'static str, &'static [&'static str])> {
        vec![]
    }

    /// Used-export rules with optional exclusions.
    fn used_export_rules(&self) -> Vec<UsedExportRule> {
        self.used_exports()
            .into_iter()
            .map(|(pattern, exports)| UsedExportRule::from_static(pattern, exports))
            .collect()
    }

    /// Class member names the framework invokes at runtime. Matching members
    /// are skipped during `unused-class-members` analysis. Intended for
    /// interface/contract patterns where the library calls methods on consumer
    /// classes (e.g. ag-Grid's `agInit`, Web Components' `connectedCallback`).
    fn used_class_members(&self) -> &'static [&'static str] {
        &[]
    }

    /// Heritage-scoped class member rules. Each rule applies only to classes
    /// matching its `extends` and/or `implements` clause. Used for frameworks
    /// where lifecycle members are runtime-invoked only on classes that extend
    /// a known base (e.g. Lit's `render`/`updated` on classes extending
    /// `LitElement`, native Web Components' `connectedCallback` on classes
    /// extending `HTMLElement`). Default: empty. Plugins override when they
    /// need scoping; flat names should still come from `used_class_members`.
    fn used_class_member_rules(&self) -> Vec<UsedClassMemberRule> {
        Vec::new()
    }

    /// Exact package-backed framework contracts that type-aware analysis may
    /// verify for latent class-member candidates.
    fn framework_class_member_contracts(&self) -> Vec<SemanticFrameworkContract> {
        Vec::new()
    }

    /// Glob patterns for test fixture files consumed by this framework.
    /// These files are implicitly used by the test runner and should not be
    /// flagged as unused. Unlike `always_used()`, this carries semantic intent
    /// for reporting purposes.
    fn fixture_glob_patterns(&self) -> &'static [&'static str] {
        &[]
    }

    /// Hidden directory names that should be traversed when this plugin is active.
    ///
    /// These are consulted before normal plugin execution because source discovery
    /// runs first. Keep entries static and package-convention scoped.
    fn discovery_hidden_dirs(&self) -> &'static [&'static str] {
        &[]
    }

    /// Dependencies that are tooling (used via CLI/config, not source imports).
    /// These should not be flagged as unused devDependencies.
    fn tooling_dependencies(&self) -> &'static [&'static str] {
        &[]
    }

    /// Import prefixes that are virtual modules provided by this framework at build time.
    /// Imports matching these prefixes should not be flagged as unlisted dependencies.
    /// Each entry is matched as a prefix against the extracted package name
    /// (e.g., `"@theme/"` matches `@theme/Layout`).
    fn virtual_module_prefixes(&self) -> &'static [&'static str] {
        &[]
    }

    /// Package name suffixes that are virtual modules provided by this framework
    /// at build time (e.g., test runner mock conventions).
    /// Imports matching these suffixes should not be flagged as unlisted dependencies.
    /// Each entry is matched as a suffix against the extracted package name
    /// (e.g., `"/__mocks__"` matches `@aws-sdk/__mocks__` and `some-pkg/__mocks__`).
    fn virtual_package_suffixes(&self) -> &'static [&'static str] {
        &[]
    }

    /// Import suffixes for build-time generated relative imports.
    ///
    /// Unresolved relative imports whose specifier ends with one of these suffixes
    /// will not be flagged as unresolved. For example, SvelteKit generates
    /// `./$types` imports in route files, returning `"/$types"` suppresses those.
    fn generated_import_patterns(&self) -> &'static [&'static str] {
        &[]
    }

    /// Import prefixes for generated type-only relative imports.
    ///
    /// Unresolved type-only imports whose specifier starts with one of these prefixes
    /// will not be flagged as unresolved. Runtime imports are still reported.
    fn generated_type_import_prefixes(&self) -> &'static [&'static str] {
        &[]
    }

    /// Path alias mappings provided by this framework at build time.
    ///
    /// Returns a list of `(prefix, replacement_dir)` tuples. When an import starting
    /// with `prefix` fails to resolve, the resolver will substitute the prefix with
    /// `replacement_dir` (relative to the project root) and retry.
    ///
    /// Called once when plugins are activated. The project `root` is provided so
    /// plugins can inspect the filesystem (e.g., Nuxt checks whether `app/` exists
    /// to determine the `srcDir`).
    fn path_aliases(&self, _root: &Path) -> Vec<(&'static str, String)> {
        vec![]
    }

    /// Directories this framework serves at a URL mount by convention, so a
    /// root-absolute reference in ANY HTML document in the project names a file
    /// inside one.
    ///
    /// Called once when plugins are activated, with the project `root`, so a
    /// plugin can require the directory to exist before claiming it.
    ///
    /// Distinct from the config-file mounts a tool declares from
    /// `resolve_config` (Storybook `staticDirs`), which stay scoped to that
    /// tool's own documents. A convention here describes how the whole project
    /// is served, so it is not scoped that way.
    fn static_dir_mappings(&self, _root: &Path) -> Vec<(std::path::PathBuf, String)> {
        vec![]
    }

    /// Convention-based auto-imports provided by this framework.
    ///
    /// Returns the names this framework exposes to user code by filesystem
    /// convention with no explicit `import` statement (e.g. Nuxt `components/`
    /// resolved by `<Card001 />` template tags), each mapped to the source file
    /// providing the export. When a file references one of these names without an
    /// import, the resolver synthesizes a graph edge to `source`.
    ///
    /// Called once when plugins are activated. The project `root` is provided so
    /// plugins can scan the convention directories on the filesystem. The table is
    /// a function of which files exist on disk, so it is rebuilt every run and is
    /// never folded into per-file extraction caching. See issue #704.
    ///
    /// A rule with an empty `scope` is visible to the files under `root` only.
    /// A plugin can set `scope` itself to make a rule visible to more roots.
    /// After the plugin runs, a shared step links a Nuxt app and each layer
    /// outside it in both directions. See issue #2752.
    fn auto_imports(&self, _root: &Path) -> Vec<AutoImportRule> {
        Vec::new()
    }

    /// File-scoped dependency providers contributed by this framework.
    fn provided_dependencies(&self) -> Vec<ProvidedDependencyRule> {
        Vec::new()
    }

    /// Check whether parsed package.json metadata activates this plugin.
    fn is_enabled_with_package_json(&self, _pkg: &PackageJson, _root: &Path) -> bool {
        false
    }

    /// Resolve parsed package.json metadata into dynamic plugin facts.
    fn resolve_package_json(&self, _pkg: &PackageJson, _root: &Path) -> PluginResult {
        PluginResult::default()
    }

    /// Dependencies referenced by the package's own package.json metadata.
    ///
    /// Unlike config-derived dependencies, these credits apply only to the
    /// package.json that produced them.
    fn package_json_referenced_dependencies(
        &self,
        _pkg: &PackageJson,
        _root: &Path,
    ) -> Vec<String> {
        Vec::new()
    }

    /// Parse a config file's AST to discover additional entries, dependencies, etc.
    ///
    /// Called for each config file matching `config_patterns()`. The source code
    /// and parsed AST are provided, use [`config_parser`] utilities to extract values.
    fn resolve_config(&self, _config_path: &Path, _source: &str, _root: &Path) -> PluginResult {
        PluginResult::default()
    }

    /// Binaries whose `--config` / `-c` argument in a package script names a
    /// config file of this plugin.
    ///
    /// A script such as `vitest run --config vitest.e2e.config.ts` points the
    /// tool at a file that no `config_patterns()` entry matches. The plugin
    /// system sends that file to `resolve_config` and credits its default
    /// export as used.
    fn script_config_binaries(&self) -> &'static [&'static str] {
        &[]
    }

    /// The key name in package.json that holds inline configuration for this tool.
    /// When set (e.g., `"jest"` for the `"jest"` key in package.json), the plugin
    /// system will extract that key's value and call `resolve_config` with its
    /// JSON content if no standalone config file was found.
    fn package_json_config_key(&self) -> Option<&'static str> {
        None
    }
}

fn builtin_entry_point_role(name: &str) -> EntryPointRole {
    if TEST_ENTRY_POINT_PLUGINS.contains(&name) {
        EntryPointRole::Test
    } else if RUNTIME_ENTRY_POINT_PLUGINS.contains(&name) {
        EntryPointRole::Runtime
    } else {
        EntryPointRole::Support
    }
}

/// Macro to eliminate boilerplate in plugin implementations.
///
/// Generates a struct and a `Plugin` trait impl with the standard static methods
/// (`name`, `enablers`, `entry_patterns`, `config_patterns`, `always_used`, `tooling_dependencies`,
/// `fixture_glob_patterns`, `virtual_module_prefixes`, `virtual_package_suffixes`,
/// `generated_type_import_prefixes`, `used_exports`).
///
/// For plugins that need custom `resolve_config()` or `is_enabled()`, keep those as
/// manual `impl Plugin for ...` blocks instead of using this macro.
///
/// # Usage
///
/// ```ignore
/// // Simple plugin (most common):
/// define_plugin! {
///     struct VitePlugin => "vite",
///     enablers: ENABLERS,
///     entry_patterns: ENTRY_PATTERNS,
///     config_patterns: CONFIG_PATTERNS,
///     always_used: ALWAYS_USED,
///     tooling_dependencies: TOOLING_DEPENDENCIES,
/// }
///
/// // Plugin with used_exports:
/// define_plugin! {
///     struct RemixPlugin => "remix",
///     enablers: ENABLERS,
///     entry_patterns: ENTRY_PATTERNS,
///     always_used: ALWAYS_USED,
///     tooling_dependencies: TOOLING_DEPENDENCIES,
///     used_exports: [("app/routes/**/*.{ts,tsx}", ROUTE_EXPORTS)],
/// }
///
/// // Plugin with imports-only resolve_config (extracts imports from config as deps):
/// define_plugin! {
///     struct CypressPlugin => "cypress",
///     enablers: ENABLERS,
///     entry_patterns: ENTRY_PATTERNS,
///     config_patterns: CONFIG_PATTERNS,
///     always_used: ALWAYS_USED,
///     tooling_dependencies: TOOLING_DEPENDENCIES,
///     resolve_config: imports_only,
/// }
///
/// // Plugin with custom resolve_config body:
/// define_plugin! {
///     struct RollupPlugin => "rollup",
///     enablers: ENABLERS,
///     config_patterns: CONFIG_PATTERNS,
///     always_used: ALWAYS_USED,
///     tooling_dependencies: TOOLING_DEPENDENCIES,
///     resolve_config(config_path, source, _root) {
///         let mut result = PluginResult::default();
///         // custom config parsing...
///         result
///     }
/// }
/// ```
///
/// All fields except `struct` and `enablers` are optional and default to `&[]` / `vec![]`.
macro_rules! define_plugin {
    (
        struct $name:ident => $display:expr,
        enablers: $enablers:expr
        $(, entry_patterns: $entry:expr)?
        $(, config_patterns: $config:expr)?
        $(, always_used: $always:expr)?
        $(, tooling_dependencies: $tooling:expr)?
        $(, fixture_glob_patterns: $fixtures:expr)?
        $(, discovery_hidden_dirs: $hidden_dirs:expr)?
        $(, virtual_module_prefixes: $virtual:expr)?
        $(, virtual_package_suffixes: $virtual_suffixes:expr)?
        $(, generated_type_import_prefixes: $generated_type_prefixes:expr)?
        $(, provided_dependencies: $provided_dependencies:expr)?
        $(, used_exports: [$( ($pat:expr, $exports:expr) ),* $(,)?])?
        , resolve_config: imports_only
        $(,)?
    ) => {
        pub struct $name;

        impl Plugin for $name {
            fn name(&self) -> &'static str {
                $display
            }

            fn enablers(&self) -> &'static [&'static str] {
                $enablers
            }

            $( fn entry_patterns(&self) -> &'static [&'static str] { $entry } )?
            $( fn config_patterns(&self) -> &'static [&'static str] { $config } )?
            $( fn always_used(&self) -> &'static [&'static str] { $always } )?
            $( fn tooling_dependencies(&self) -> &'static [&'static str] { $tooling } )?
            $( fn fixture_glob_patterns(&self) -> &'static [&'static str] { $fixtures } )?
            $( fn discovery_hidden_dirs(&self) -> &'static [&'static str] { $hidden_dirs } )?
            $( fn virtual_module_prefixes(&self) -> &'static [&'static str] { $virtual } )?
            $( fn virtual_package_suffixes(&self) -> &'static [&'static str] { $virtual_suffixes } )?
            $( fn generated_type_import_prefixes(&self) -> &'static [&'static str] { $generated_type_prefixes } )?
            $( fn provided_dependencies(&self) -> Vec<ProvidedDependencyRule> { $provided_dependencies } )?

            $(
                fn used_exports(&self) -> Vec<(&'static str, &'static [&'static str])> {
                    vec![$( ($pat, $exports) ),*]
                }
            )?

            fn resolve_config(
                &self,
                config_path: &std::path::Path,
                source: &str,
                _root: &std::path::Path,
            ) -> PluginResult {
                let mut result = PluginResult::default();
                crate::plugins::add_import_referenced_dependencies(
                    &mut result,
                    source,
                    config_path,
                );
                result
            }
        }
    };

    (
        struct $name:ident => $display:expr,
        enablers: $enablers:expr
        $(, entry_patterns: $entry:expr)?
        $(, config_patterns: $config:expr)?
        $(, always_used: $always:expr)?
        $(, tooling_dependencies: $tooling:expr)?
        $(, fixture_glob_patterns: $fixtures:expr)?
        $(, discovery_hidden_dirs: $hidden_dirs:expr)?
        $(, virtual_module_prefixes: $virtual:expr)?
        $(, virtual_package_suffixes: $virtual_suffixes:expr)?
        $(, generated_type_import_prefixes: $generated_type_prefixes:expr)?
        $(, provided_dependencies: $provided_dependencies:expr)?
        $(, package_json_config_key: $pkg_key:expr)?
        $(, script_config_binaries: $script_binaries:expr)?
        $(, used_exports: [$( ($pat:expr, $exports:expr) ),* $(,)?])?
        , resolve_config($cp:ident, $src:ident, $root:ident) $body:block
        $(,)?
    ) => {
        pub struct $name;

        impl Plugin for $name {
            fn name(&self) -> &'static str {
                $display
            }

            fn enablers(&self) -> &'static [&'static str] {
                $enablers
            }

            $( fn entry_patterns(&self) -> &'static [&'static str] { $entry } )?
            $( fn config_patterns(&self) -> &'static [&'static str] { $config } )?
            $( fn always_used(&self) -> &'static [&'static str] { $always } )?
            $( fn tooling_dependencies(&self) -> &'static [&'static str] { $tooling } )?
            $( fn fixture_glob_patterns(&self) -> &'static [&'static str] { $fixtures } )?
            $( fn discovery_hidden_dirs(&self) -> &'static [&'static str] { $hidden_dirs } )?
            $( fn virtual_module_prefixes(&self) -> &'static [&'static str] { $virtual } )?
            $( fn virtual_package_suffixes(&self) -> &'static [&'static str] { $virtual_suffixes } )?
            $( fn generated_type_import_prefixes(&self) -> &'static [&'static str] { $generated_type_prefixes } )?
            $( fn provided_dependencies(&self) -> Vec<ProvidedDependencyRule> { $provided_dependencies } )?

            $(
                fn package_json_config_key(&self) -> Option<&'static str> {
                    Some($pkg_key)
                }
            )?

            $(
                fn used_exports(&self) -> Vec<(&'static str, &'static [&'static str])> {
                    vec![$( ($pat, $exports) ),*]
                }
            )?

            $( fn script_config_binaries(&self) -> &'static [&'static str] { $script_binaries } )?

            fn resolve_config(
                &self,
                $cp: &std::path::Path,
                $src: &str,
                $root: &std::path::Path,
            ) -> PluginResult
            $body
        }
    };

    (
        struct $name:ident => $display:expr,
        enablers: $enablers:expr
        $(, entry_patterns: $entry:expr)?
        $(, config_patterns: $config:expr)?
        $(, always_used: $always:expr)?
        $(, tooling_dependencies: $tooling:expr)?
        $(, fixture_glob_patterns: $fixtures:expr)?
        $(, discovery_hidden_dirs: $hidden_dirs:expr)?
        $(, virtual_module_prefixes: $virtual:expr)?
        $(, virtual_package_suffixes: $virtual_suffixes:expr)?
        $(, generated_type_import_prefixes: $generated_type_prefixes:expr)?
        $(, provided_dependencies: $provided_dependencies:expr)?
        $(, package_json_config_key: $pkg_key:expr)?
        $(, used_exports: [$( ($pat:expr, $exports:expr) ),* $(,)?])?
        $(,)?
    ) => {
        pub struct $name;

        impl Plugin for $name {
            fn name(&self) -> &'static str {
                $display
            }

            fn enablers(&self) -> &'static [&'static str] {
                $enablers
            }

            $( fn entry_patterns(&self) -> &'static [&'static str] { $entry } )?
            $( fn config_patterns(&self) -> &'static [&'static str] { $config } )?
            $( fn always_used(&self) -> &'static [&'static str] { $always } )?
            $( fn tooling_dependencies(&self) -> &'static [&'static str] { $tooling } )?
            $( fn fixture_glob_patterns(&self) -> &'static [&'static str] { $fixtures } )?
            $( fn discovery_hidden_dirs(&self) -> &'static [&'static str] { $hidden_dirs } )?
            $( fn virtual_module_prefixes(&self) -> &'static [&'static str] { $virtual } )?
            $( fn virtual_package_suffixes(&self) -> &'static [&'static str] { $virtual_suffixes } )?
            $( fn generated_type_import_prefixes(&self) -> &'static [&'static str] { $generated_type_prefixes } )?
            $( fn provided_dependencies(&self) -> Vec<ProvidedDependencyRule> { $provided_dependencies } )?

            $(
                fn package_json_config_key(&self) -> Option<&'static str> {
                    Some($pkg_key)
                }
            )?

            $(
                fn used_exports(&self) -> Vec<(&'static str, &'static [&'static str])> {
                    vec![$( ($pat, $exports) ),*]
                }
            )?
        }
    };
}

pub mod config_parser;
mod config_value_credits;
mod manifest;
pub mod manifest_entries;
pub mod registry;
mod tooling;

pub(crate) use module_federation::runtime_remotes;
pub use registry::{
    AggregatedPluginResult, PluginRegistry, PluginToolingDependencies, PluginToolingEvidence,
};
pub use tooling::types_package_target;
pub(crate) use tooling::{
    cli_tooling_config_patterns, is_ambient_types_package, is_known_tooling_dependency,
};

fn add_import_referenced_dependencies(result: &mut PluginResult, source: &str, config_path: &Path) {
    let imports = config_parser::extract_imports(source, config_path);
    for import in &imports {
        result
            .referenced_dependencies
            .push(crate::resolve::extract_package_name(import));
    }
}

/// Credit the optional peer dependencies a test environment loads at runtime.
///
/// The rules are data: see the `test-environment-optional-peer` rows in
/// `crates/core/data/config_value_credits.toml`. `jsdom` requires its optional
/// peer `canvas` lazily when it is installed, so a project installing it for
/// real canvas support has no import of it anywhere and would see the
/// dependency reported as unused (issue #2005). Environments without such a
/// peer, like `happy-dom`, have no row.
///
/// Only names already declared in the manifest can be credited, so this never
/// invents an unlisted dependency.
fn credit_environment_optional_peers(environment: &str, result: &mut PluginResult) {
    credit_config_value(
        config_value_credits::CreditSurface::TestEnvironmentOptionalPeer,
        canonical_test_environment(environment),
        result,
    );
}

/// Record the catalogue credits for a config value, if any.
///
/// Returns whether a rule matched, which callers use when the credited packages
/// replace the dependencies derived from the value itself.
fn credit_config_value(
    surface: config_value_credits::CreditSurface,
    value: &str,
    result: &mut PluginResult,
) -> bool {
    let Some(packages) = config_value_credits::credited_packages(surface, value) else {
        return false;
    };
    result
        .referenced_dependencies
        .extend(packages.iter().cloned());
    true
}

/// Strip the runner prefix from a test environment specifier.
///
/// Both runners accept the bare name and the package it resolves to, so
/// `testEnvironment: "jest-environment-jsdom"` and `environment: "jsdom"` select
/// the same environment. Matching the literal short name only meant the fully
/// qualified form, which the Jest docs use and projects copy, was treated as a
/// third-party environment and missed its optional-peer credit.
fn canonical_test_environment(environment: &str) -> &str {
    environment
        .strip_prefix("jest-environment-")
        .or_else(|| environment.strip_prefix("vitest-environment-"))
        .unwrap_or(environment)
}

mod adonis;
mod ag_ui;
mod angular;
mod astro;
mod ava;
mod babel;
mod biome;
mod browser_extension;
mod bun;
mod c8;
mod capacitor;
mod changesets;
mod commit_and_tag_version;
mod commitizen;
mod commitlint;
mod content_collections;
mod contentlayer;
mod convex;
mod cspell;
mod cucumber;
mod cypress;
mod danger;
mod deno;
mod dependency_cruiser;
mod docusaurus;
mod drizzle;
mod electron;
mod ember;
mod eslint;
mod eve;
mod expo;
mod expo_router;
mod firebase;
mod fumadocs;
mod gatsby;
mod graphql_codegen;
mod hardhat;
mod husky;
mod i18next;
mod ionic;
mod jest;
mod k6;
mod karma;
mod kibana;
mod knex;
mod kysely;
mod lefthook;
mod lexical;
mod lint_staged;
mod lit;
mod markdownlint;
mod mintlify;
mod mocha;
mod module_federation;
mod msw;
mod napi_rs;
mod nest_commander;
mod nestjs;
mod nestjs_trpc;
mod next_intl;
mod nextjs;
mod nitro;
mod nodemon;
pub(crate) mod nuxt;
mod nx;
mod nyc;
mod obsidian;
mod openapi_ts;
mod opencode;
mod opennext_cloudflare;
mod oxfmt;
mod oxlint;
mod pandacss;
mod parcel;
mod pinia;
mod pkg_utils;
mod playwright;
mod plop;
mod pm2;
mod pnpm;
mod postcss;
mod prettier;
mod prisma;
mod qwik;
mod react_compiler;
mod react_native;
mod react_router;
mod redwoodsdk;
mod relay;
mod release_it;
mod remark;
mod remix;
mod rolldown;
mod rollup;
mod rsbuild;
mod rspack;
mod rspress;
mod sanity;
mod semantic_release;
mod sentry;
mod simple_git_hooks;
mod size_limit;
mod storybook;
mod stryker;
mod stylelint;
mod supabase;
mod sveltekit;
mod svgo;
mod svgr;
mod swc;
mod syncpack;
mod tailwind;
mod tanstack_router;
mod tap;
mod test_alias;
mod tsd;
mod tsdown;
mod tsup;
mod turborepo;
mod typedoc;
mod typeorm;
mod typescript;
mod unocss;
mod varlock;
mod velite;
mod vercel;
mod vite;
mod vitepress;
mod vitest;
mod vscode;
mod waku;
mod webdriverio;
mod webpack;
mod wrangler;
mod wuchale;
mod wxt;

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn segment_regexes_split_on_the_native_separator() {
        let regexes = vec![Regex::new("^_(components|hooks)$").expect("valid regex")];
        assert!(matches_segment_regex(
            "src/pages/_components/a.tsx",
            &regexes
        ));
        assert!(!matches_segment_regex(
            "src/pages/components/a.tsx",
            &regexes
        ));
        assert_eq!(
            matches_segment_regex("src\\pages\\_components\\a.tsx", &regexes),
            cfg!(windows),
            "a backslash separates segments only where it is the native separator"
        );
    }
    use std::path::Path;

    #[test]
    fn is_enabled_with_deps_exact_match() {
        let plugin = nextjs::NextJsPlugin;
        let deps = vec!["next".to_string()];
        assert!(plugin.is_enabled_with_deps(&deps, Path::new("/project")));
    }

    #[test]
    fn is_enabled_with_deps_no_match() {
        let plugin = nextjs::NextJsPlugin;
        let deps = vec!["react".to_string()];
        assert!(!plugin.is_enabled_with_deps(&deps, Path::new("/project")));
    }

    #[test]
    fn is_enabled_with_deps_empty_deps() {
        let plugin = nextjs::NextJsPlugin;
        let deps: Vec<String> = vec![];
        assert!(!plugin.is_enabled_with_deps(&deps, Path::new("/project")));
    }

    #[test]
    fn environment_optional_peers_come_from_the_credit_catalogue() {
        for environment in [
            "jsdom",
            "jest-environment-jsdom",
            "vitest-environment-jsdom",
        ] {
            let mut result = PluginResult::default();
            credit_environment_optional_peers(environment, &mut result);
            assert_eq!(
                result.referenced_dependencies,
                vec!["canvas".to_string()],
                "expected the catalogue credit for {environment}"
            );
        }
    }

    #[test]
    fn environment_without_a_catalogue_row_credits_nothing() {
        let mut result = PluginResult::default();
        credit_environment_optional_peers("happy-dom", &mut result);
        assert!(result.referenced_dependencies.is_empty());
    }

    #[test]
    fn entry_point_role_defaults_are_centralized() {
        assert_eq!(vite::VitePlugin.entry_point_role(), EntryPointRole::Runtime);
        assert_eq!(
            vitest::VitestPlugin.entry_point_role(),
            EntryPointRole::Test
        );
        assert_eq!(
            storybook::StorybookPlugin.entry_point_role(),
            EntryPointRole::Support
        );
        assert_eq!(
            obsidian::ObsidianPlugin.entry_point_role(),
            EntryPointRole::Runtime
        );
        assert_eq!(knex::KnexPlugin.entry_point_role(), EntryPointRole::Support);
    }

    #[test]
    fn plugins_with_entry_patterns_have_explicit_role_intent() {
        let runtime_or_test_or_support: rustc_hash::FxHashSet<&'static str> =
            TEST_ENTRY_POINT_PLUGINS
                .iter()
                .chain(RUNTIME_ENTRY_POINT_PLUGINS.iter())
                .chain(SUPPORT_ENTRY_POINT_PLUGINS.iter())
                .copied()
                .collect();

        for plugin in crate::plugins::registry::builtin::create_builtin_plugins() {
            if plugin.entry_patterns().is_empty() {
                continue;
            }
            assert!(
                runtime_or_test_or_support.contains(plugin.name()),
                "plugin '{}' exposes entry patterns but is missing from the entry-point role map",
                plugin.name()
            );
        }
    }

    /// The registry skips a config whose result `is_empty`, so every field that
    /// carries a contribution must make the result non-empty on its own.
    #[test]
    fn plugin_result_is_empty_only_when_every_field_is_empty() {
        type Fill = fn(&mut PluginResult);

        assert!(PluginResult::default().is_empty());

        let rows: [(&str, Fill); 16] = [
            ("entry_patterns", |r| {
                r.entry_patterns.push(PathRule::new("src/*.ts"));
            }),
            ("used_exports", |r| {
                r.used_exports
                    .push(UsedExportRule::new("src/*.ts", ["default"]));
            }),
            ("used_class_members", |r| {
                r.used_class_members
                    .push(UsedClassMemberRule::from("render"));
            }),
            ("referenced_dependencies", |r| {
                r.referenced_dependencies.push("lodash".to_string());
            }),
            ("package_referenced_dependencies", |r| {
                r.package_referenced_dependencies
                    .push((PathBuf::from("/project/pkg"), "lodash".to_string()));
            }),
            ("always_used_files", |r| {
                r.always_used_files.push("**/*.stories.tsx".to_string());
            }),
            ("path_aliases", |r| {
                r.path_aliases.push(("@".to_string(), "src".to_string()));
            }),
            ("setup_files", |r| {
                r.setup_files.push(PathBuf::from("/setup.ts"));
            }),
            ("fixture_patterns", |r| {
                r.fixture_patterns.push("**/__fixtures__/**/*".to_string());
            }),
            ("scss_include_paths", |r| {
                r.scss_include_paths.push(PathBuf::from("/project/styles"));
            }),
            ("static_dir_mappings", |r| {
                r.static_dir_mappings
                    .push((PathBuf::from("/project/public"), "/".to_string()));
            }),
            ("framework_static_dir_mappings", |r| {
                r.framework_static_dir_mappings
                    .push((PathBuf::from("/project/static"), "/".to_string()));
            }),
            ("provided_dependencies", |r| {
                r.provided_dependencies.push(ProvidedDependencyRule::new(
                    "**/*.stories.tsx",
                    ["react"],
                    Vec::<String>::new(),
                ));
            }),
            ("config_diagnostics", |r| {
                r.config_diagnostics
                    .push(PluginConfigDiagnostic::unreadable(
                        Path::new("/project/webpack.config.js"),
                        "webpack",
                        "exposes",
                        "dynamic-value",
                    ));
            }),
            ("federation_sources", |r| {
                r.federation_sources.push(FederationSource {
                    target: FederationSourceTarget::Remote("app".to_string()),
                    config_path: PathBuf::from("/project/webpack.config.js"),
                    plugin: "webpack".to_string(),
                    key: "remotes",
                });
            }),
            ("jsx_import_sources", |r| {
                r.jsx_import_sources.push(JsxImportSourceRule {
                    source: "./src/jsx".to_string(),
                    config_dir: PathBuf::from("/project"),
                    include: vec!["src/**/*.test.tsx".to_string()],
                });
            }),
        ];

        for (field, fill) in rows {
            let mut result = PluginResult::default();
            fill(&mut result);
            assert!(
                !result.is_empty(),
                "a result with only {field} set must not be empty"
            );
        }
    }

    #[test]
    fn is_enabled_with_deps_prefix_match() {
        let plugin = storybook::StorybookPlugin;
        let deps = vec!["@storybook/react".to_string()];
        assert!(plugin.is_enabled_with_deps(&deps, Path::new("/project")));
    }

    #[test]
    fn is_enabled_with_deps_prefix_no_match_without_slash() {
        let plugin = storybook::StorybookPlugin;
        let deps = vec!["@storybookish".to_string()];
        assert!(!plugin.is_enabled_with_deps(&deps, Path::new("/project")));
    }

    #[test]
    fn is_enabled_with_deps_multiple_enablers() {
        let plugin = vitest::VitestPlugin;
        let deps_vitest = vec!["vitest".to_string()];
        let deps_none = vec!["mocha".to_string()];
        assert!(plugin.is_enabled_with_deps(&deps_vitest, Path::new("/project")));
        assert!(!plugin.is_enabled_with_deps(&deps_none, Path::new("/project")));
    }

    #[test]
    fn plugin_resolve_config_default_returns_empty() {
        let plugin = commitizen::CommitizenPlugin;
        let result = plugin.resolve_config(
            Path::new("/project/config.js"),
            "const x = 1;",
            Path::new("/project"),
        );
        assert!(result.is_empty());
    }

    #[test]
    fn is_enabled_with_deps_exact_and_prefix_both_work() {
        let plugin = storybook::StorybookPlugin;
        let deps_exact = vec!["storybook".to_string()];
        assert!(plugin.is_enabled_with_deps(&deps_exact, Path::new("/project")));
        let deps_prefix = vec!["@storybook/vue3".to_string()];
        assert!(plugin.is_enabled_with_deps(&deps_prefix, Path::new("/project")));
    }

    #[test]
    fn is_enabled_with_deps_multiple_enablers_remix() {
        let plugin = remix::RemixPlugin;
        let deps_node = vec!["@remix-run/node".to_string()];
        assert!(plugin.is_enabled_with_deps(&deps_node, Path::new("/project")));
        let deps_react = vec!["@remix-run/react".to_string()];
        assert!(plugin.is_enabled_with_deps(&deps_react, Path::new("/project")));
        let deps_cf = vec!["@remix-run/cloudflare".to_string()];
        assert!(plugin.is_enabled_with_deps(&deps_cf, Path::new("/project")));
    }

    struct MinimalPlugin;
    impl Plugin for MinimalPlugin {
        fn name(&self) -> &'static str {
            "minimal"
        }
    }

    #[test]
    fn default_resolve_config_returns_empty() {
        let r = MinimalPlugin.resolve_config(
            Path::new("config.js"),
            "export default {}",
            Path::new("/"),
        );
        assert!(r.is_empty());
    }

    #[test]
    fn default_package_json_metadata_hooks_are_empty() {
        let pkg = PackageJson::default();
        assert!(!MinimalPlugin.is_enabled_with_package_json(&pkg, Path::new("/")));
        assert!(
            MinimalPlugin
                .resolve_package_json(&pkg, Path::new("/"))
                .is_empty()
        );
    }

    #[test]
    fn default_is_enabled_returns_false_when_no_enablers() {
        let deps = vec!["anything".to_string()];
        assert!(!MinimalPlugin.is_enabled_with_deps(&deps, Path::new("/")));
    }

    #[test]
    fn all_builtin_plugin_names_are_non_empty_and_unique() {
        let plugins = registry::builtin::create_builtin_plugins();
        let mut seen = std::collections::BTreeSet::new();
        for p in &plugins {
            let name = p.name();
            assert!(
                !name.is_empty(),
                "builtin plugins must have a non-empty name"
            );
            assert!(seen.insert(name), "duplicate plugin name: {name}");
        }
    }

    #[test]
    fn all_builtin_plugins_have_activation_signals() {
        // Plugins activated from package metadata or filesystem sentinels rather
        // than dependency enablers (napi binary name; deno.json presence;
        // kibana.jsonc presence).
        const NON_DEPENDENCY_ACTIVATED_PLUGINS: &[&str] = &["napi-rs", "deno", "kibana"];
        let plugins = registry::builtin::create_builtin_plugins();
        for p in &plugins {
            assert!(
                !p.enablers().is_empty()
                    || !p.script_enablers().is_empty()
                    || NON_DEPENDENCY_ACTIVATED_PLUGINS.contains(&p.name()),
                "plugin '{}' has no activation signal",
                p.name()
            );
        }
    }

    #[test]
    fn plugins_with_config_patterns_have_always_used() {
        let plugins = registry::builtin::create_builtin_plugins();
        for p in &plugins {
            if !p.config_patterns().is_empty() {
                assert!(
                    !p.always_used().is_empty(),
                    "plugin '{}' has config_patterns but no always_used",
                    p.name()
                );
            }
        }
    }

    #[test]
    fn framework_plugins_enablers() {
        let cases: Vec<(&dyn Plugin, &[&str])> = vec![
            (&nextjs::NextJsPlugin, &["next"]),
            (&nuxt::NuxtPlugin, &["nuxt"]),
            (&angular::AngularPlugin, &["@angular/core"]),
            (&ionic::IonicPlugin, &["@ionic/angular"]),
            (&sveltekit::SvelteKitPlugin, &["@sveltejs/kit"]),
            (&gatsby::GatsbyPlugin, &["gatsby"]),
        ];
        for (plugin, expected_enablers) in cases {
            let enablers = plugin.enablers();
            for expected in expected_enablers {
                assert!(
                    enablers.contains(expected),
                    "plugin '{}' should have '{}'",
                    plugin.name(),
                    expected
                );
            }
        }
    }

    #[test]
    fn testing_plugins_enablers() {
        let cases: Vec<(&dyn Plugin, &str)> = vec![
            (&jest::JestPlugin, "jest"),
            (&vitest::VitestPlugin, "vitest"),
            (&playwright::PlaywrightPlugin, "@playwright/test"),
            (&cypress::CypressPlugin, "cypress"),
            (&mocha::MochaPlugin, "mocha"),
            (&stryker::StrykerPlugin, "@stryker-mutator/core"),
        ];
        for (plugin, enabler) in cases {
            assert!(
                plugin.enablers().contains(&enabler),
                "plugin '{}' should have '{}'",
                plugin.name(),
                enabler
            );
        }
    }

    #[test]
    fn bundler_plugins_enablers() {
        let cases: Vec<(&dyn Plugin, &str)> = vec![
            (&vite::VitePlugin, "vite"),
            (&webpack::WebpackPlugin, "webpack"),
            (&rollup::RollupPlugin, "rollup"),
        ];
        for (plugin, enabler) in cases {
            assert!(
                plugin.enablers().contains(&enabler),
                "plugin '{}' should have '{}'",
                plugin.name(),
                enabler
            );
        }
    }

    #[test]
    fn test_plugins_have_test_entry_patterns() {
        let test_plugins: Vec<&dyn Plugin> = vec![
            &bun::BunPlugin,
            &deno::DenoPlugin,
            &jest::JestPlugin,
            &vitest::VitestPlugin,
            &mocha::MochaPlugin,
            &tap::TapPlugin,
            &tsd::TsdPlugin,
        ];
        for plugin in test_plugins {
            let patterns = plugin.entry_patterns();
            assert!(
                !patterns.is_empty(),
                "test plugin '{}' should have entry patterns",
                plugin.name()
            );
            assert!(
                patterns
                    .iter()
                    .any(|p| p.contains("test") || p.contains("spec") || p.contains("__tests__")),
                "test plugin '{}' should have test/spec patterns",
                plugin.name()
            );
        }
    }

    #[test]
    fn framework_plugins_have_entry_patterns() {
        let plugins: Vec<&dyn Plugin> = vec![
            &nextjs::NextJsPlugin,
            &nuxt::NuxtPlugin,
            &angular::AngularPlugin,
            &sveltekit::SvelteKitPlugin,
        ];
        for plugin in plugins {
            assert!(
                !plugin.entry_patterns().is_empty(),
                "framework plugin '{}' should have entry patterns",
                plugin.name()
            );
        }
    }

    #[test]
    fn plugins_with_resolve_config_have_config_patterns() {
        let plugins: Vec<&dyn Plugin> = vec![
            &jest::JestPlugin,
            &vitest::VitestPlugin,
            &babel::BabelPlugin,
            &eslint::EslintPlugin,
            &webpack::WebpackPlugin,
            &storybook::StorybookPlugin,
            &typescript::TypeScriptPlugin,
            &postcss::PostCssPlugin,
            &nextjs::NextJsPlugin,
            &nuxt::NuxtPlugin,
            &angular::AngularPlugin,
            &nx::NxPlugin,
            &stryker::StrykerPlugin,
            &wuchale::WuchalePlugin,
            &rollup::RollupPlugin,
            &sveltekit::SvelteKitPlugin,
            &prettier::PrettierPlugin,
            &contentlayer::ContentlayerPlugin,
        ];
        for plugin in plugins {
            assert!(
                !plugin.config_patterns().is_empty(),
                "plugin '{}' with resolve_config should have config_patterns",
                plugin.name()
            );
        }
    }

    #[test]
    fn plugin_tooling_deps_include_enabler_package() {
        let plugins: Vec<&dyn Plugin> = vec![
            &jest::JestPlugin,
            &vitest::VitestPlugin,
            &webpack::WebpackPlugin,
            &typescript::TypeScriptPlugin,
            &eslint::EslintPlugin,
            &prettier::PrettierPlugin,
            &danger::DangerPlugin,
            &stryker::StrykerPlugin,
            &wuchale::WuchalePlugin,
            &contentlayer::ContentlayerPlugin,
        ];
        for plugin in plugins {
            let tooling = plugin.tooling_dependencies();
            let enablers = plugin.enablers();
            assert!(
                enablers
                    .iter()
                    .any(|e| !e.ends_with('/') && tooling.contains(e)),
                "plugin '{}': at least one non-prefix enabler should be in tooling_dependencies",
                plugin.name()
            );
        }
    }

    #[test]
    fn nextjs_has_used_exports_for_pages() {
        let plugin = nextjs::NextJsPlugin;
        let exports = plugin.used_exports();
        assert!(!exports.is_empty());
        assert!(exports.iter().any(|(_, names)| names.contains(&"default")));
    }

    #[test]
    fn remix_has_used_exports_for_routes() {
        let plugin = remix::RemixPlugin;
        let exports = plugin.used_exports();
        assert!(!exports.is_empty());
        let route_entry = exports.iter().find(|(pat, _)| pat.contains("routes"));
        assert!(route_entry.is_some());
        let (_, names) = route_entry.unwrap();
        assert!(names.contains(&"loader"));
        assert!(names.contains(&"action"));
        assert!(names.contains(&"default"));
    }

    #[test]
    fn sveltekit_has_used_exports_for_routes() {
        let plugin = sveltekit::SvelteKitPlugin;
        let exports = plugin.used_exports();
        assert!(!exports.is_empty());
        assert!(exports.iter().any(|(_, names)| names.contains(&"GET")));
    }

    #[test]
    fn nuxt_has_hash_virtual_prefix() {
        assert!(nuxt::NuxtPlugin.virtual_module_prefixes().contains(&"#"));
    }

    #[test]
    fn sveltekit_has_dollar_virtual_prefixes() {
        let prefixes = sveltekit::SvelteKitPlugin.virtual_module_prefixes();
        assert!(prefixes.contains(&"$app/"));
        assert!(prefixes.contains(&"$env/"));
        assert!(prefixes.contains(&"$lib/"));
    }

    #[test]
    fn sveltekit_has_lib_path_alias() {
        let aliases = sveltekit::SvelteKitPlugin.path_aliases(Path::new("/project"));
        assert!(aliases.iter().any(|(prefix, _)| *prefix == "$lib/"));
    }

    #[test]
    fn nuxt_has_tilde_path_alias() {
        let aliases = nuxt::NuxtPlugin.path_aliases(Path::new("/nonexistent"));
        assert!(aliases.iter().any(|(prefix, _)| *prefix == "~/"));
        assert!(aliases.iter().any(|(prefix, _)| *prefix == "~~/"));
    }

    #[test]
    fn jest_has_package_json_config_key() {
        assert_eq!(jest::JestPlugin.package_json_config_key(), Some("jest"));
    }

    #[test]
    fn tsd_has_package_json_config_key() {
        assert_eq!(tsd::TsdPlugin.package_json_config_key(), Some("tsd"));
    }

    #[test]
    fn babel_has_package_json_config_key() {
        assert_eq!(babel::BabelPlugin.package_json_config_key(), Some("babel"));
    }

    #[test]
    fn eslint_has_package_json_config_key() {
        assert_eq!(
            eslint::EslintPlugin.package_json_config_key(),
            Some("eslintConfig")
        );
    }

    #[test]
    fn prettier_has_package_json_config_key() {
        assert_eq!(
            prettier::PrettierPlugin.package_json_config_key(),
            Some("prettier")
        );
    }

    #[test]
    fn macro_generated_plugin_basic_properties() {
        let plugin = msw::MswPlugin;
        assert_eq!(plugin.name(), "msw");
        assert!(plugin.enablers().contains(&"msw"));
        assert!(!plugin.entry_patterns().is_empty());
        assert!(plugin.config_patterns().is_empty());
        assert!(!plugin.always_used().is_empty());
        assert!(!plugin.tooling_dependencies().is_empty());
    }

    #[test]
    fn macro_generated_plugin_with_used_exports() {
        let plugin = remix::RemixPlugin;
        assert_eq!(plugin.name(), "remix");
        assert!(!plugin.used_exports().is_empty());
    }

    #[test]
    fn macro_passes_through_virtual_package_suffixes() {
        define_plugin! {
            struct MacroSuffixSmokePlugin => "macro-suffix-smoke",
            enablers: &["macro-suffix-smoke"],
            virtual_package_suffixes: &["/__macro_smoke__"],
        }

        let plugin = MacroSuffixSmokePlugin;
        assert_eq!(
            plugin.virtual_package_suffixes(),
            &["/__macro_smoke__"],
            "macro-declared virtual_package_suffixes must propagate to the trait method"
        );
    }

    #[test]
    fn macro_generated_plugin_imports_only_resolve_config() {
        let plugin = cypress::CypressPlugin;
        let source = r"
            import { defineConfig } from 'cypress';
            import coveragePlugin from '@cypress/code-coverage';
            export default defineConfig({});
        ";
        let result = plugin.resolve_config(
            Path::new("cypress.config.ts"),
            source,
            Path::new("/project"),
        );
        assert!(
            result
                .referenced_dependencies
                .contains(&"cypress".to_string())
        );
        assert!(
            result
                .referenced_dependencies
                .contains(&"@cypress/code-coverage".to_string())
        );
    }

    #[test]
    fn builtin_plugin_count_is_expected() {
        let plugins = registry::builtin::create_builtin_plugins();
        assert!(
            plugins.len() >= 110,
            "expected at least 110 built-in plugins, got {}",
            plugins.len()
        );
    }

    /// A pattern that climbs out of its workspace with `../` resolves against
    /// the workspace prefix, so it names a file in a sibling workspace. A climb
    /// past the project root stays unresolved and matches no project file.
    #[test]
    fn a_parent_relative_pattern_resolves_against_the_workspace_prefix() {
        let parent_relative = |pattern: &str| {
            let mut rule = PathRule::new(pattern);
            rule.parent_relative = true;
            rule
        };
        assert_eq!(
            parent_relative("../shared/src/Thing.tsx")
                .prefixed("packages/app")
                .pattern,
            "packages/shared/src/Thing.tsx"
        );
        assert_eq!(
            parent_relative("../../lib/index.{ts,js}")
                .prefixed("apps/web/client")
                .pattern,
            "apps/lib/index.{ts,js}"
        );
        assert!(
            parent_relative("../../../outside/Thing.tsx")
                .prefixed("packages/app")
                .pattern
                .starts_with("../"),
            "a climb past the project root matches no project file"
        );
        assert_eq!(
            parent_relative("src/index.ts")
                .prefixed("packages/app")
                .pattern,
            "packages/app/src/index.ts"
        );
    }

    /// On Windows the workspace prefix uses backslashes, so a sibling-workspace
    /// pattern must climb the same segments as with forward slashes.
    #[test]
    fn a_parent_relative_pattern_resolves_against_a_backslash_prefix() {
        let mut rule = PathRule::new("../../packages/ui/src/**/*.mdx");
        rule.parent_relative = true;
        assert_eq!(
            rule.prefixed("apps\\docs").pattern,
            "packages/ui/src/**/*.mdx"
        );
    }

    /// Any other pattern keeps the plain prefix, so a config-directory-relative
    /// `../src/**` does not climb out of its workspace.
    #[test]
    fn a_plain_parent_pattern_is_not_resolved() {
        assert_eq!(
            PathRule::new("../src/**/*.stories.tsx")
                .prefixed("packages/ui")
                .pattern,
            "packages/ui/../src/**/*.stories.tsx"
        );
    }
}