fallow_core/plugins/

mod.rs

//! Plugin system for framework-aware codebase analysis.
//!
//! Plugins read JS, TS and JSON config files with the Oxc parser and walk the
//! AST. They never run JavaScript. Each plugin implements the [`Plugin`] trait
//! with static defaults (entry patterns, config file patterns, used exports)
//! and reads config files for entries, 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",
    "jasmine",
    "jest",
    "k6",
    "mocha",
    "playwright",
    "rstest",
    "tap",
    "tsd",
    "vitest",
    "webdriverio",
];

const RUNTIME_ENTRY_POINT_PLUGINS: &[&str] = &[
    "adonis",
    "angular",
    "astro",
    "browser-extension",
    "convex",
    "docusaurus",
    "egg",
    "electron",
    "ember",
    "eve",
    "expo",
    "expo-router",
    "flue",
    "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",
    "vite-plus",
    "vitepress",
    "waku",
    "webpack",
    "wrangler",
    "wxt",
];

/// Whether an entry rule of `result` matches the project-relative `path`, as
/// entry point discovery compiles and matches the rules.
#[cfg(test)]
pub(crate) fn entry_rules_match(result: &PluginResult, path: &str) -> bool {
    result
        .entry_patterns
        .iter()
        .filter_map(|rule| CompiledPathRule::for_entry_rule(rule, "entry pattern"))
        .any(|rule| rule.matches(path))
}

#[cfg(test)]
const SUPPORT_ENTRY_POINT_PLUGINS: &[&str] = &[
    "alchemy",
    "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>,
    /// Exports that the tool reads from the files a config names. These rules
    /// join the config-file export credit, so they count only under
    /// `includeEntryExports`. Unlike `used_exports`, they never make an entry
    /// point reportable when `includeEntryExports` is off.
    entry_export_credits: 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>,
    /// Runtime packages that the JSX transform of a config imports when the
    /// config sets no import source. The analysis credits a package only when
    /// a matching file has JSX and no pragma. These rules never add a graph
    /// edge.
    jsx_package_credits: Vec<JsxImportSourceRule>,
    /// The directories of the tsconfig files that set the JSX runtime of
    /// TypeScript files, through `jsxImportSource` or a `jsx` mode that adds
    /// no automatic runtime import. Vite then does not use the default
    /// `react` runtime for the TypeScript files below these directories.
    tsconfig_jsx_dirs: Vec<PathBuf>,
}

/// 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
}

/// Export names that frameworks read as configuration, not as code.
///
/// A plugin `used_exports` rule can list these names next to real handlers
/// (Next.js lists `dynamic` next to `GET` and `default`). Only a listed name
/// with a literal value counts as configuration, so the review brief does not
/// ask for a test of it. Extend this set when a new plugin adds a
/// configuration-only export. Never add a name that holds behavior, such as
/// `generateMetadata`, `loader` or a route handler.
pub const CONFIG_ONLY_EXPORT_NAMES: &[&str] = &[
    "dynamic",
    "dynamicParams",
    "revalidate",
    "fetchCache",
    "runtime",
    "preferredRegion",
    "maxDuration",
    "prerender",
    "config",
    "metadata",
    "viewport",
];

/// 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}"));
    }

    /// 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.entry_export_credits.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()
            && self.jsx_package_credits.is_empty()
            && self.tsconfig_jsx_dirs.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, Hash)]
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)
    }

    /// A rule for a tool glob with extglob groups, such as `!(*.spec)`. The
    /// rule matches at least the paths that the tool matches. Each negated
    /// group becomes an excluded glob.
    #[must_use]
    pub(crate) fn from_extglob(pattern: &str) -> Self {
        let rewritten = fallow_config::extglob::rewrite_include(pattern);
        Self::new(rewritten.include).with_excluded_globs(rewritten.excludes)
    }

    /// Exclude the paths of tool globs with extglob groups. An excluded glob
    /// never removes more paths than the tool does, so a glob with a negated
    /// group excludes nothing.
    #[must_use]
    pub(crate) fn with_excluded_extglobs<I, S>(self, patterns: I) -> Self
    where
        I: IntoIterator<Item = S>,
        S: AsRef<str>,
    {
        let excluded: Vec<String> = patterns
            .into_iter()
            .filter_map(|pattern| fallow_config::extglob::rewrite_exclude(pattern.as_ref()))
            .collect();
        self.with_excluded_globs(excluded)
    }

    #[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 prefix = |pattern: &str| {
            if self.parent_relative && pattern.starts_with("../") {
                resolve_parent_relative_pattern(pattern, ws_prefix)
            } else {
                prefix_workspace_pattern(pattern, ws_prefix)
            }
        };
        Self {
            pattern: prefix(&self.pattern),
            exclude_globs: self
                .exclude_globs
                .iter()
                .map(|pattern| prefix(pattern))
                .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 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))
    }
}

/// Compile the include glob of an entry rule. Its `*` stays in one path
/// segment, and it accepts an empty alternative, such as `{,m}js`, because
/// the rewrite of an extglob `?(m)` group gives one.
pub(crate) fn entry_rule_glob(pattern: &str) -> Result<globset::Glob, globset::Error> {
    globset::GlobBuilder::new(pattern)
        .literal_separator(true)
        .empty_alternates(true)
        .build()
}

/// A compiled path rule matcher shared by entry-point and used-export matching.
///
/// Every glob accepts an empty alternative, such as `{,m}js`, because the
/// rewrite of an extglob `?(m)` group gives one.
#[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 entry_rule_glob(&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,
            ),
        })
    }

    pub(crate) fn for_used_export_rule(rule: &PathRule, rule_kind: &str) -> Option<Self> {
        Self::for_entry_rule(rule, rule_kind)
    }

    #[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)
                .empty_alternates(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] {
        &[]
    }

    /// Config patterns whose files do not get the `default` export credit.
    ///
    /// Under `includeEntryExports`, the `default` export of a file that one of
    /// [`Self::config_patterns`] matches counts as used, because the tool loads
    /// the config file and reads its default export. List a pattern here when
    /// the tool reads named exports instead, or when the pattern also matches
    /// ordinary source files. Each entry must be identical to an entry of
    /// [`Self::config_patterns`].
    fn config_default_export_opt_out(&self) -> &'static [&'static str] {
        &[]
    }

    /// Tool config files and the export names that the tool reads from them.
    ///
    /// Under `includeEntryExports`, these exports of a matching file count as
    /// used. `"*"` credits every export. Use this for a config file that is not
    /// in [`Self::config_patterns`], or for a tool that reads named exports.
    /// Each pattern is anchored: it gets the workspace prefix but no `**/`
    /// prefix, so it matches only at the project or workspace package root.
    /// This credit never changes the output without `includeEntryExports`.
    fn config_file_exports(&self) -> &'static [(&'static str, &'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()
    }

    /// Parse a config file with the project root known.
    ///
    /// `root` is the package root that [`Plugin::resolve_config`] receives. In
    /// a workspace run it is the workspace package directory. `project_root`
    /// is the analysis root. A plugin that reads more files from paths that
    /// the config names must keep each read inside `project_root`, because the
    /// config comes from the analyzed repository. The default ignores
    /// `project_root`.
    fn resolve_config_in_project(
        &self,
        config_path: &Path,
        source: &str,
        root: &Path,
        _project_root: &Path,
    ) -> PluginResult {
        self.resolve_config(config_path, source, root)
    }

    /// Parse a config file that a package script passes with `--config` or
    /// `-c`. The script runs the tool in `root`, also for a config in a
    /// subdirectory. The default is [`Plugin::resolve_config_in_project`].
    fn resolve_script_config(
        &self,
        config_path: &Path,
        source: &str,
        root: &Path,
        project_root: &Path,
    ) -> PluginResult {
        self.resolve_config_in_project(config_path, source, root, project_root)
    }

    /// 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)?
        $(, config_default_export_opt_out: $config_opt_out:expr)?
        $(, config_file_exports: $config_exports: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 config_default_export_opt_out(&self) -> &'static [&'static str] { $config_opt_out } )?
            $( fn config_file_exports(&self) -> &'static [(&'static str, &'static [&'static str])] { $config_exports } )?
            $( 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)?
        $(, config_default_export_opt_out: $config_opt_out:expr)?
        $(, config_file_exports: $config_exports: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
        $(, resolve_config_in_project($pcp:ident, $psrc:ident, $proot:ident, $pproj:ident) $pbody: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 config_default_export_opt_out(&self) -> &'static [&'static str] { $config_opt_out } )?
            $( fn config_file_exports(&self) -> &'static [(&'static str, &'static [&'static str])] { $config_exports } )?
            $( 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

            $(
                fn resolve_config_in_project(
                    &self,
                    $pcp: &std::path::Path,
                    $psrc: &str,
                    $proot: &std::path::Path,
                    $pproj: &std::path::Path,
                ) -> PluginResult
                $pbody
            )?
        }
    };

    (
        struct $name:ident => $display:expr,
        enablers: $enablers:expr
        $(, entry_patterns: $entry:expr)?
        $(, config_patterns: $config:expr)?
        $(, config_default_export_opt_out: $config_opt_out:expr)?
        $(, config_file_exports: $config_exports: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 config_default_export_opt_out(&self) -> &'static [&'static str] { $config_opt_out } )?
            $( fn config_file_exports(&self) -> &'static [(&'static str, &'static [&'static str])] { $config_exports } )?
            $( 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 flue;
mod jasmine;
mod manifest;
pub mod manifest_entries;
mod mise;
mod osls;
mod project_glob;
mod railway;
pub mod registry;
mod rstest;
mod serverless_framework;
mod textlint;
mod tooling;
mod trace_provenance;
mod used_export_names;
mod used_export_rule;

pub(crate) use used_export_rule::ConfigExportCredit;
pub use used_export_rule::{PluginUsedExportRule, UsedExportRule};

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,
};
pub use trace_provenance::{ExportCredits, build_trace_provenance};
pub use used_export_names::UsedExportNames;

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. A match on the short name only missed the fully
/// qualified form that the Jest docs use, so that form lost its 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 alchemy;
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 egg;
mod electron;
mod ember;
mod eslint;
mod eve;
mod expo;
mod expo_router;
mod firebase;
mod fumadocs;
mod gatsby;
mod github_action;
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 opentelemetry;
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 typescript_content_mapper;
mod unocss;
mod varlock;
mod velite;
mod vercel;
mod vite;
pub(crate) mod vite_plus;
mod vitepress;
mod vitest;
mod vscode;
mod waku;
mod webdriverio;
mod webpack;
mod wrangler;
mod wuchale;
mod wxt;

#[cfg(test)]
mod tests;