fallow-config 3.35.0

use std::collections::BTreeMap;
use std::fmt;
use std::path::{Path, PathBuf};
use std::str::FromStr;

use schemars::JsonSchema;
use serde::{Deserialize, Deserializer, Serialize, Serializer, de::Error as _};

use crate::config::UsedClassMemberRule;

/// Supported plugin file extensions.
/// The file extensions of external plugin files.
pub const PLUGIN_EXTENSIONS: &[&str] = &["toml", "json", "jsonc"];

/// How a plugin's discovered entry points contribute to coverage reachability.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, JsonSchema, Default)]
#[serde(rename_all = "camelCase")]
pub enum EntryPointRole {
    /// Runtime/application roots that should count toward runtime reachability.
    Runtime,
    /// Test roots that should count toward test reachability.
    Test,
    /// Support/setup/config roots that should keep files alive but not count as runtime/test.
    #[default]
    Support,
}

/// Which export shape a convention auto-import credits when its name is
/// referenced without an explicit `import` statement.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AutoImportKind {
    /// `import { name } from source` (named export, e.g. a Nuxt composable/util).
    Named,
    /// `import name from source` (default export).
    Default,
    /// SFC default export consumed by a template tag (Nuxt `components/`).
    DefaultComponent,
}

/// A single convention-based auto-import: a bare identifier name that resolves
/// to an export in `source` by framework convention, with no explicit `import`
/// statement in the consuming file.
///
/// Built by `Plugin::auto_imports` from a filesystem scan (e.g. Nuxt scanning
/// `components/`), and consumed at graph-build time: the resolver matches a
/// file's captured `auto_import_candidates` against these rules and synthesizes
/// an edge to `source`. The table is a function of which files exist on disk,
/// not of any single file's bytes, so it is computed fresh per run and never
/// cached as part of per-file extraction.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AutoImportRule {
    /// Bare identifier name (e.g. `useCounter`, `Card001`, `BaseButton`,
    /// `LazyCard001`). Component names are canonical PascalCase; the consuming
    /// scanner normalizes kebab-case tags before matching.
    pub name: String,
    /// Absolute path to the source file providing the export.
    pub source: PathBuf,
    /// Which export to credit when the name is referenced.
    pub kind: AutoImportKind,
    /// Absolute roots whose files can reference the name: the root that
    /// declared the rule, plus the roots that share its names, such as a Nuxt
    /// app and the layers it extends. A file outside every root gets no edge.
    /// Empty means every file, and the plugin run fills it with its own root.
    pub scope: Vec<PathBuf>,
}

impl AutoImportRule {
    /// A rule with no scope yet. The plugin run scopes it to its own root.
    #[must_use]
    pub const fn new(name: String, source: PathBuf, kind: AutoImportKind) -> Self {
        Self {
            name,
            source,
            kind,
            scope: Vec::new(),
        }
    }
}

/// A JSX import source that a bundler or test config sets for a group of files.
///
/// With the automatic JSX runtime, the transform adds an import of
/// `<source>/jsx-dev-runtime` to each file with JSX, and no import statement
/// shows that edge. A per-file `@jsxImportSource` pragma overrides the config,
/// so the resolver applies a rule only to a module with
/// `jsx_runtime_from_config` set. Built from the config each run and never
/// cached with per-file extraction.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct JsxImportSourceRule {
    /// The `importSource` value as written, for example `./src/jsx` or
    /// `preact`.
    pub source: String,
    /// Absolute directory of the config file. The `include` globs match paths
    /// relative to it, and a relative `source` that does not resolve from the
    /// file resolves from it.
    pub config_dir: PathBuf,
    /// Glob patterns, relative to `config_dir`, of the files that the config
    /// transforms.
    pub include: Vec<String>,
    /// Glob patterns, relative to `config_dir`, of the files that the config
    /// does not transform, also when `include` matches them.
    pub exclude: Vec<String>,
}

/// How to detect if a plugin should be activated.
///
/// When set on an `ExternalPluginDef`, this takes priority over `enablers`.
/// Supports dependency checks, file existence checks, and boolean combinators.
#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(tag = "type", rename_all = "camelCase")]
pub enum PluginDetection {
    /// Plugin detected if this package is in dependencies.
    Dependency {
        /// Exact package name looked up in the project's declared dependencies.
        package: String,
    },
    /// Plugin detected if this file pattern matches.
    FileExists {
        /// Project-root-relative glob; the plugin activates when any
        /// discovered file matches it. Validated at load like other user
        /// globs (no absolute paths or `..` segments).
        /// A single `*` stays within one path segment; use `**` to match across directories.
        pattern: String,
    },
    /// All conditions must be true.
    All {
        /// Sub-conditions combined with logical AND.
        conditions: Vec<Self>,
    },
    /// Any condition must be true.
    Any {
        /// Sub-conditions combined with logical OR.
        conditions: Vec<Self>,
    },
}

/// A declarative plugin definition loaded from a standalone file or inline config.
///
/// External plugins provide the same static pattern capabilities as built-in
/// plugins (entry points, always-used files, used exports, tooling dependencies),
/// but are defined in standalone files or inline in the fallow config rather than
/// compiled Rust code.
///
/// They cannot do AST-based config parsing (`resolve_config()`), but cover the
/// vast majority of framework integration use cases.
///
/// Supports JSONC, JSON, and TOML formats. All use camelCase field names.
///
/// ```json
/// {
///   "$schema": "https://raw.githubusercontent.com/fallow-rs/fallow/main/plugin-schema.json",
///   "name": "my-framework",
///   "enablers": ["my-framework", "@my-framework/core"],
///   "entryPoints": ["src/routes/**/*.{ts,tsx}"],
///   "configPatterns": ["my-framework.config.{ts,js}"],
///   "alwaysUsed": ["src/setup.ts"],
///   "toolingDependencies": ["my-framework-cli"],
///   "usedExports": [
///     { "pattern": "src/routes/**/*.{ts,tsx}", "exports": ["default", "loader", "action"] }
///   ]
/// }
/// ```
#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ExternalPluginDef {
    /// JSON Schema reference (ignored during deserialization).
    #[serde(rename = "$schema", default, skip_serializing)]
    #[schemars(skip)]
    pub schema: Option<String>,

    /// Unique name for this plugin.
    pub name: String,

    /// Rich detection logic (dependency checks, file existence, boolean combinators).
    /// Takes priority over `enablers` when set.
    #[serde(default)]
    pub detection: Option<PluginDetection>,

    /// Package names that activate this plugin when found in package.json.
    /// Supports exact matches and prefix patterns (ending with `/`).
    /// Only used when `detection` is not set.
    #[serde(default)]
    pub enablers: Vec<String>,

    /// Glob patterns for entry point files.
    #[serde(default)]
    pub entry_points: Vec<String>,

    /// Coverage role for `entryPoints`.
    ///
    /// Defaults to `support`. Set to `runtime` for application entry points
    /// or `test` for test framework entry points.
    #[serde(default = "default_external_entry_point_role")]
    pub entry_point_role: EntryPointRole,

    /// Entry points DERIVED from framework manifest files.
    ///
    /// Unlike `entryPoints` (static globs), each rule finds manifest files by a
    /// recursive glob, parses them, and seeds sibling entries resolved relative
    /// to each manifest's directory, gated on the manifest's own fields. Seeded
    /// entries use this plugin's `entryPointRole`.
    #[serde(default)]
    pub manifest_entries: Vec<ManifestEntryRule>,

    /// Glob patterns for config files (marked as always-used when active).
    #[serde(default)]
    pub config_patterns: Vec<String>,

    /// Entries of `configPatterns` whose files do not get the `default`
    /// export credit under `includeEntryExports`. Use it when the tool reads
    /// named exports, or when the pattern also matches ordinary source files.
    /// Write each entry exactly as in `configPatterns`. Other entries have
    /// no effect.
    #[serde(default)]
    pub config_default_export_opt_out: Vec<String>,

    /// Files that are always considered "used" when this plugin is active.
    #[serde(default)]
    pub always_used: Vec<String>,

    /// Dependencies that are tooling (used via CLI/config, not source imports).
    /// These should not be flagged as unused devDependencies.
    #[serde(default)]
    pub tooling_dependencies: Vec<String>,

    /// Exports that are always considered used for matching file patterns.
    #[serde(default)]
    pub used_exports: Vec<ExternalUsedExport>,

    /// Class member method/property rules the framework invokes at runtime.
    /// Supports plain member names for global suppression and scoped objects
    /// with `extends` / `implements` constraints when the method name is too
    /// common to suppress across the whole workspace.
    #[serde(default)]
    pub used_class_members: Vec<UsedClassMemberRule>,
}

/// Exports considered used for files matching a pattern.
#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
pub struct ExternalUsedExport {
    /// Glob pattern for files.
    /// A single `*` stays within one path segment; use `**` to match across directories.
    pub pattern: String,
    /// Export names always considered used.
    pub exports: Vec<String>,
}

/// Format of the manifest files a [`ManifestEntryRule`] reads.
///
/// `jsonc` (the default) also parses plain JSON, so it is the tolerant choice.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, JsonSchema, Default)]
#[serde(rename_all = "lowercase")]
pub enum ManifestFormat {
    /// JSONC (comments + trailing commas). Also accepts plain JSON.
    #[default]
    Jsonc,
    /// Strict JSON.
    Json,
}

/// A validated field path into a manifest document.
///
/// Field paths use dotted object keys and an exact `[*]` segment for array
/// traversal. The parsed segments are retained so evaluators do not repeatedly
/// interpret user-authored path strings.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct ManifestFieldPath {
    raw: String,
    segments: Vec<ManifestFieldSegment>,
}

/// One validated traversal step in a [`ManifestFieldPath`].
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum ManifestFieldSegment {
    /// Read one named key from each current JSON object.
    Key(String),
    /// Visit every item in each current JSON array.
    Each,
}

impl ManifestFieldPath {
    /// The original validated path, used in diagnostics and serialization.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.raw
    }

    /// Parsed object-key and array traversal segments in source order.
    #[must_use]
    pub fn segments(&self) -> &[ManifestFieldSegment] {
        &self.segments
    }

    fn parse(raw: String) -> Result<Self, String> {
        if raw.is_empty() {
            return Err("manifest field path must not be empty".to_string());
        }

        let mut segments = Vec::new();
        for component in raw.split('.') {
            if component.is_empty() {
                return Err(format!(
                    "manifest field path '{raw}' contains an empty segment"
                ));
            }

            let key_end = component.find('[').unwrap_or(component.len());
            let key = &component[..key_end];
            if key.is_empty() || key.contains(['{', '}', ']']) {
                return Err(format!(
                    "manifest field path '{raw}' contains unsupported bracket syntax"
                ));
            }
            segments.push(ManifestFieldSegment::Key(key.to_string()));

            let mut suffix = &component[key_end..];
            while !suffix.is_empty() {
                let Some(rest) = suffix.strip_prefix("[*]") else {
                    return Err(format!(
                        "manifest field path '{raw}' only supports exact '[*]' array traversal"
                    ));
                };
                segments.push(ManifestFieldSegment::Each);
                suffix = rest;
            }
        }

        Ok(Self { raw, segments })
    }
}

impl FromStr for ManifestFieldPath {
    type Err = String;

    fn from_str(raw: &str) -> Result<Self, Self::Err> {
        Self::parse(raw.to_string())
    }
}

impl fmt::Display for ManifestFieldPath {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.raw)
    }
}

impl Serialize for ManifestFieldPath {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_str(&self.raw)
    }
}

impl<'de> Deserialize<'de> for ManifestFieldPath {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let raw = String::deserialize(deserializer)?;
        Self::parse(raw).map_err(D::Error::custom)
    }
}

/// One parsed part of a manifest entry path template.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ManifestPathPart {
    /// Literal path text copied without interpretation.
    Literal(String),
    /// A manifest field whose scalar values are interpolated.
    Field(ManifestFieldPath),
}

/// A validated manifest-relative entry path with parsed `${field.path}` parts.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ManifestPathTemplate {
    raw: String,
    parts: Vec<ManifestPathPart>,
}

impl ManifestPathTemplate {
    /// The original template used for serialization and diagnostics.
    #[must_use]
    pub fn as_str(&self) -> &str {
        &self.raw
    }

    /// Parsed literal and field parts in source order.
    #[must_use]
    pub fn parts(&self) -> &[ManifestPathPart] {
        &self.parts
    }

    /// Replace field interpolations with a safe segment for glob validation.
    #[must_use]
    pub fn validation_pattern(&self) -> String {
        let mut pattern = String::with_capacity(self.raw.len());
        for part in &self.parts {
            match part {
                ManifestPathPart::Literal(literal) => pattern.push_str(literal),
                ManifestPathPart::Field(_) => pattern.push_str("fallowinterp"),
            }
        }
        pattern
    }

    fn parse(raw: String) -> Result<Self, String> {
        let mut parts = Vec::new();
        let mut rest = raw.as_str();

        while let Some(start) = rest.find("${") {
            if start > 0 {
                parts.push(ManifestPathPart::Literal(rest[..start].to_string()));
            }

            let after = &rest[start + 2..];
            let Some(end) = after.find('}') else {
                return Err(format!(
                    "manifest entry path '{raw}' contains an unterminated interpolation"
                ));
            };
            let field = after[..end].parse::<ManifestFieldPath>()?;
            parts.push(ManifestPathPart::Field(field));
            rest = &after[end + 1..];
        }

        if !rest.is_empty() {
            parts.push(ManifestPathPart::Literal(rest.to_string()));
        }
        if parts.is_empty() {
            parts.push(ManifestPathPart::Literal(String::new()));
        }

        Ok(Self { raw, parts })
    }
}

impl FromStr for ManifestPathTemplate {
    type Err = String;

    fn from_str(raw: &str) -> Result<Self, Self::Err> {
        Self::parse(raw.to_string())
    }
}

impl fmt::Display for ManifestPathTemplate {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.raw)
    }
}

impl Serialize for ManifestPathTemplate {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: Serializer,
    {
        serializer.serialize_str(&self.raw)
    }
}

impl<'de> Deserialize<'de> for ManifestPathTemplate {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: Deserializer<'de>,
    {
        let raw = String::deserialize(deserializer)?;
        Self::parse(raw).map_err(D::Error::custom)
    }
}

/// A typed condition used by a manifest entry gate.
///
/// Plain JSON values retain strict equality semantics. The reserved
/// `{ "exists": bool }` object tests field presence without truthiness.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
#[serde(untagged)]
pub enum ManifestCondition {
    /// Require the field path to resolve (`true`) or not resolve (`false`).
    Exists(ManifestExistsPredicate),
    /// Require at least one yielded value to equal this JSON value exactly.
    Equals(serde_json::Value),
}

/// The explicit field-presence predicate accepted by [`ManifestCondition`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub struct ManifestExistsPredicate {
    /// Whether the field path must resolve to at least one value.
    pub exists: bool,
}

/// A rule that seeds entry points DERIVED from framework manifest files.
///
/// For every file matching `manifests` (a recursive glob) that passes the
/// manifest-level `when` gate, each rule in `entries` is resolved relative to
/// the manifest's directory (with `${dotted.field}` interpolation) into an entry
/// point. Seeded entries use the owning plugin's `entryPointRole`.
///
/// ```jsonc
/// {
///   "manifests": "**/kibana.jsonc",
///   "when": { "type": "plugin" },
///   "entries": [
///     { "path": "public/index.{ts,tsx}", "when": { "plugin.browser": true } },
///     { "path": "server/index.{ts,tsx}", "when": { "plugin.server": true } },
///     { "path": "${plugin.extraPublicDirs}/index.{ts,tsx}" }
///   ]
/// }
/// ```
#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ManifestEntryRule {
    /// Recursive glob selecting the manifest files to read (e.g. `**/kibana.jsonc`).
    /// A single `*` stays within one path segment; use `**` to match across directories.
    pub manifests: String,

    /// Manifest format. Defaults to `jsonc` (which also parses plain JSON).
    #[serde(default)]
    pub format: ManifestFormat,

    /// Manifest-level gate: a map of field path to an equality expectation or
    /// an explicit `exists` predicate. Paths use dotted object keys and may
    /// traverse arrays with `[*]`. ALL entries must match; a wildcard equality
    /// matches when any yielded value equals the expectation. An empty map
    /// matches every manifest.
    #[serde(default)]
    #[schemars(with = "BTreeMap<String, ManifestCondition>")]
    pub when: BTreeMap<ManifestFieldPath, ManifestCondition>,

    /// Entry rules seeded per matching manifest.
    pub entries: Vec<ManifestSeedRule>,
}

/// A single entry seeded by a [`ManifestEntryRule`], resolved relative to the
/// manifest's directory.
#[derive(Debug, Clone, Deserialize, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
pub struct ManifestSeedRule {
    /// Entry glob relative to the manifest directory. May contain
    /// `${dotted.field}` interpolation that fans out over string / array
    /// manifest field values; `[*]` traverses object arrays. A missing or empty
    /// field seeds nothing. The glob must encode its own extension, such as
    /// `public/index.{ts,tsx}`. Glob entry patterns are matched literally
    /// against discovered files without
    /// source-extension probing.
    #[schemars(with = "String")]
    pub path: ManifestPathTemplate,

    /// Per-entry gate, using the same strict equality and `[*]` traversal as the
    /// manifest-level gate. An empty map always passes.
    #[serde(default)]
    #[schemars(with = "BTreeMap<String, ManifestCondition>")]
    pub when: BTreeMap<ManifestFieldPath, ManifestCondition>,
}

fn default_external_entry_point_role() -> EntryPointRole {
    EntryPointRole::Support
}

impl ExternalPluginDef {
    /// Generate JSON Schema for the external plugin format.
    #[must_use]
    pub fn json_schema() -> serde_json::Value {
        serde_json::to_value(schemars::schema_for!(ExternalPluginDef)).unwrap_or_default()
    }

    /// Validate all user-supplied glob patterns on this plugin definition,
    /// including patterns nested inside `detection` combinators (`all` / `any`).
    ///
    /// Pattern names use the same `framework[].<field>` notation used by
    /// inline plugin definitions in `FallowConfig::validate_user_globs` so the
    /// user sees consistent field paths whether the plugin is inline or
    /// loaded from `.fallow/plugins/` / `fallow-plugin-*.{toml,json,jsonc}`.
    ///
    /// # Errors
    ///
    /// Returns a non-empty `Vec` of
    /// [`GlobValidationError`](crate::config::glob_validation::GlobValidationError)
    /// when any pattern is rejected.
    pub fn validate_user_globs(
        &self,
    ) -> Result<(), Vec<crate::config::glob_validation::GlobValidationError>> {
        use crate::config::glob_validation::{compile_user_glob, validate_user_globs};

        let mut errors = Vec::new();
        validate_user_globs(&self.entry_points, "framework[].entryPoints", &mut errors);
        validate_user_globs(&self.always_used, "framework[].alwaysUsed", &mut errors);
        validate_user_globs(
            &self.config_patterns,
            "framework[].configPatterns",
            &mut errors,
        );
        for used in &self.used_exports {
            if let Err(e) = compile_user_glob(&used.pattern, "framework[].usedExports[].pattern") {
                errors.push(e);
            }
        }
        for rule in &self.manifest_entries {
            if let Err(e) =
                compile_user_glob(&rule.manifests, "framework[].manifestEntries[].manifests")
            {
                errors.push(e);
            }
            for seed in &rule.entries {
                // Substitute `${...}` interpolation with a placeholder segment so
                // the surrounding glob (e.g. `${x}/index.{ts,tsx}`) validates.
                let probe = seed.path.validation_pattern();
                if let Err(e) =
                    compile_user_glob(&probe, "framework[].manifestEntries[].entries[].path")
                {
                    errors.push(e);
                }
            }
        }
        if let Some(detection) = &self.detection {
            validate_detection_user_globs(detection, "framework[].detection", &mut errors);
        }
        if errors.is_empty() {
            Ok(())
        } else {
            Err(errors)
        }
    }
}

/// Recursively validate `FileExists.pattern` fields inside a `PluginDetection`
/// tree. `All` and `Any` combinators recurse into their nested conditions.
fn validate_detection_user_globs(
    detection: &PluginDetection,
    field: &'static str,
    errors: &mut Vec<crate::config::glob_validation::GlobValidationError>,
) {
    match detection {
        PluginDetection::Dependency { .. } => {}
        PluginDetection::FileExists { pattern } => {
            if let Err(e) = crate::config::glob_validation::compile_user_glob(pattern, field) {
                errors.push(e);
            }
        }
        PluginDetection::All { conditions } | PluginDetection::Any { conditions } => {
            for condition in conditions {
                validate_detection_user_globs(condition, field, errors);
            }
        }
    }
}

/// Discover external plugin definitions AND validate their user-supplied glob
/// patterns. Accumulates all errors across all loaded plugins so the user sees
/// every problem in one run.
///
/// Discovery is identical to [`discover_external_plugins`]; this wrapper adds
/// the per-plugin glob validation step required for security
/// (see issue #463: `framework[].detection.fileExists.pattern` reaches
/// `glob::glob` on disk via `root.join(pattern)`, so a `..` segment loaded
/// from `.fallow/plugins/` would be a real path traversal).
///
/// # Errors
///
/// Returns the list of validation errors when any discovered plugin contains
/// a rejected pattern. The CLI surfaces these with exit code 2.
pub fn discover_and_validate_external_plugins(
    root: &Path,
    config_plugin_paths: &[String],
) -> Result<Vec<ExternalPluginDef>, Vec<crate::config::glob_validation::GlobValidationError>> {
    let plugins = discover_external_plugins(root, config_plugin_paths);
    let mut errors = Vec::new();
    for plugin in &plugins {
        if let Err(mut plugin_errors) = plugin.validate_user_globs() {
            errors.append(&mut plugin_errors);
        }
    }
    if errors.is_empty() {
        Ok(plugins)
    } else {
        Err(errors)
    }
}

/// Detect plugin format from file extension.
enum PluginFormat {
    Toml,
    Json,
    Jsonc,
}

impl PluginFormat {
    fn from_path(path: &Path) -> Option<Self> {
        match path.extension().and_then(|e| e.to_str()) {
            Some("toml") => Some(Self::Toml),
            Some("json") => Some(Self::Json),
            Some("jsonc") => Some(Self::Jsonc),
            _ => None,
        }
    }
}

/// Check if a file has a supported plugin extension.
/// The name of the plugin directory under `.fallow/` that the loader reads.
const DEFAULT_PLUGINS_DIR_NAME: &str = "plugins";

/// The name prefix of the plugin files in the project root that the loader
/// reads.
pub const ROOT_PLUGIN_FILE_PREFIX: &str = "fallow-plugin-";

fn is_plugin_file(path: &Path) -> bool {
    path.extension()
        .and_then(|e| e.to_str())
        .is_some_and(|ext| PLUGIN_EXTENSIONS.contains(&ext))
}

/// Parse a plugin definition from file content based on format.
fn parse_plugin(content: &str, format: &PluginFormat, path: &Path) -> Option<ExternalPluginDef> {
    match format {
        PluginFormat::Toml => match toml::from_str::<ExternalPluginDef>(content) {
            Ok(plugin) => Some(plugin),
            Err(e) => {
                tracing::warn!("failed to parse external plugin {}: {e}", path.display());
                None
            }
        },
        PluginFormat::Json => match serde_json::from_str::<ExternalPluginDef>(content) {
            Ok(plugin) => Some(plugin),
            Err(e) => {
                tracing::warn!("failed to parse external plugin {}: {e}", path.display());
                None
            }
        },
        PluginFormat::Jsonc => match crate::jsonc::parse_to_value::<ExternalPluginDef>(content) {
            Ok(plugin) => Some(plugin),
            Err(e) => {
                tracing::warn!("failed to parse external plugin {}: {e}", path.display());
                None
            }
        },
    }
}

/// Why an explicitly configured external-plugin resource could not be loaded.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum ConfiguredPluginDiagnosticKind {
    /// The configured path does not exist.
    Missing,
    /// The configured path resolves outside the project root.
    OutsideProjectRoot,
    /// The configured file does not use a supported plugin extension.
    UnsupportedFormat,
    /// The configured file or directory could not be read.
    Unreadable,
    /// The configured plugin file could not be parsed into a usable definition.
    InvalidDefinition,
    /// The configured directory contains no supported plugin definitions.
    NoPluginFiles,
}

/// Typed readiness diagnostic for an explicitly configured plugin resource.
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub struct ConfiguredPluginDiagnostic {
    /// Failure classification suitable for programmatic branching.
    pub kind: ConfiguredPluginDiagnosticKind,
    /// Resolved path that was inspected. Callers must apply their own privacy policy.
    pub path: PathBuf,
}

/// Inspect only paths named explicitly by the `plugins` config field.
///
/// Automatic plugin discovery deliberately retains its existing best-effort
/// behavior. This API exists for readiness surfaces that must distinguish an
/// absent plugin configuration from an explicitly configured resource that
/// could not be loaded.
#[must_use]
pub fn diagnose_configured_external_plugins(
    root: &Path,
    config_plugin_paths: &[String],
) -> Vec<ConfiguredPluginDiagnostic> {
    let canonical_root = dunce::canonicalize(root).unwrap_or_else(|_| root.to_path_buf());
    let mut diagnostics = Vec::new();

    for path_str in config_plugin_paths {
        let path = root.join(path_str);
        let metadata = match std::fs::metadata(&path) {
            Ok(metadata) => metadata,
            Err(error) => {
                diagnostics.push(ConfiguredPluginDiagnostic {
                    kind: if error.kind() == std::io::ErrorKind::NotFound {
                        ConfiguredPluginDiagnosticKind::Missing
                    } else {
                        ConfiguredPluginDiagnosticKind::Unreadable
                    },
                    path,
                });
                continue;
            }
        };

        if !is_within_root(&path, &canonical_root) {
            diagnostics.push(ConfiguredPluginDiagnostic {
                kind: ConfiguredPluginDiagnosticKind::OutsideProjectRoot,
                path,
            });
            continue;
        }

        if metadata.is_dir() {
            diagnose_configured_plugin_dir(&path, &canonical_root, &mut diagnostics);
        } else if metadata.is_file() {
            diagnose_configured_plugin_file(&path, &canonical_root, &mut diagnostics);
        } else {
            diagnostics.push(ConfiguredPluginDiagnostic {
                kind: ConfiguredPluginDiagnosticKind::UnsupportedFormat,
                path,
            });
        }
    }

    diagnostics
}

fn diagnose_configured_plugin_dir(
    dir: &Path,
    canonical_root: &Path,
    diagnostics: &mut Vec<ConfiguredPluginDiagnostic>,
) {
    let Ok(entries) = std::fs::read_dir(dir) else {
        diagnostics.push(ConfiguredPluginDiagnostic {
            kind: ConfiguredPluginDiagnosticKind::Unreadable,
            path: dir.to_path_buf(),
        });
        return;
    };
    let mut plugin_files = Vec::new();
    let mut entry_failed = false;
    for entry in entries {
        match entry {
            Ok(entry) => {
                let path = entry.path();
                if path.is_file() && is_plugin_file(&path) {
                    plugin_files.push(path);
                }
            }
            Err(_) => {
                entry_failed = true;
                diagnostics.push(ConfiguredPluginDiagnostic {
                    kind: ConfiguredPluginDiagnosticKind::Unreadable,
                    path: dir.to_path_buf(),
                });
            }
        }
    }
    if plugin_files.is_empty() && !entry_failed {
        diagnostics.push(ConfiguredPluginDiagnostic {
            kind: ConfiguredPluginDiagnosticKind::NoPluginFiles,
            path: dir.to_path_buf(),
        });
        return;
    }
    plugin_files.sort();
    for path in plugin_files {
        diagnose_configured_plugin_file(&path, canonical_root, diagnostics);
    }
}

fn diagnose_configured_plugin_file(
    path: &Path,
    canonical_root: &Path,
    diagnostics: &mut Vec<ConfiguredPluginDiagnostic>,
) {
    let kind = if !is_within_root(path, canonical_root) {
        Some(ConfiguredPluginDiagnosticKind::OutsideProjectRoot)
    } else if let Some(format) = PluginFormat::from_path(path) {
        match std::fs::read_to_string(path) {
            Ok(content) => match parse_plugin(&content, &format, path) {
                Some(plugin) if !plugin.name.is_empty() => None,
                Some(_) | None => Some(ConfiguredPluginDiagnosticKind::InvalidDefinition),
            },
            Err(_) => Some(ConfiguredPluginDiagnosticKind::Unreadable),
        }
    } else {
        Some(ConfiguredPluginDiagnosticKind::UnsupportedFormat)
    };
    if let Some(kind) = kind {
        diagnostics.push(ConfiguredPluginDiagnostic {
            kind,
            path: path.to_path_buf(),
        });
    }
}

/// Discover and load external plugin definitions for a project.
///
/// Discovery order (first occurrence of a plugin name wins):
/// 1. Paths from the `plugins` config field (files or directories)
/// 2. `.fallow/plugins/` directory (auto-discover `*.toml`, `*.json`, `*.jsonc` files)
/// 3. Project root `fallow-plugin-*` files (`.toml`, `.json`, `.jsonc`)
pub fn discover_external_plugins(
    root: &Path,
    config_plugin_paths: &[String],
) -> Vec<ExternalPluginDef> {
    let mut plugins = Vec::new();
    let mut seen_names = rustc_hash::FxHashSet::default();

    let canonical_root = dunce::canonicalize(root).unwrap_or_else(|_| root.to_path_buf());

    load_configured_plugin_paths(
        root,
        config_plugin_paths,
        &canonical_root,
        &mut plugins,
        &mut seen_names,
    );
    load_default_plugins_dir(root, &canonical_root, &mut plugins, &mut seen_names);
    load_root_plugin_files(root, &canonical_root, &mut plugins, &mut seen_names);

    plugins
}

fn load_configured_plugin_paths(
    root: &Path,
    config_plugin_paths: &[String],
    canonical_root: &Path,
    plugins: &mut Vec<ExternalPluginDef>,
    seen_names: &mut rustc_hash::FxHashSet<String>,
) {
    for path_str in config_plugin_paths {
        let path = root.join(path_str);
        if !is_within_root(&path, canonical_root) {
            tracing::warn!("plugin path '{path_str}' resolves outside project root, skipping");
            continue;
        }
        if path.is_dir() {
            load_plugins_from_dir(&path, canonical_root, plugins, seen_names);
        } else if path.is_file() {
            load_plugin_file(&path, canonical_root, plugins, seen_names);
        }
    }
}

fn load_default_plugins_dir(
    root: &Path,
    canonical_root: &Path,
    plugins: &mut Vec<ExternalPluginDef>,
    seen_names: &mut rustc_hash::FxHashSet<String>,
) {
    let plugins_dir = root.join(".fallow").join(DEFAULT_PLUGINS_DIR_NAME);
    if plugins_dir.is_dir() && is_within_root(&plugins_dir, canonical_root) {
        load_plugins_from_dir(&plugins_dir, canonical_root, plugins, seen_names);
    }
}

fn load_root_plugin_files(
    root: &Path,
    canonical_root: &Path,
    plugins: &mut Vec<ExternalPluginDef>,
    seen_names: &mut rustc_hash::FxHashSet<String>,
) {
    for path in root_plugin_files(root) {
        load_plugin_file(&path, canonical_root, plugins, seen_names);
    }
}

/// The `fallow-plugin-*` files in the project root, sorted.
fn root_plugin_files(root: &Path) -> Vec<PathBuf> {
    let Ok(entries) = std::fs::read_dir(root) else {
        return Vec::new();
    };
    let mut plugin_files: Vec<PathBuf> = entries
        .filter_map(Result::ok)
        .map(|e| e.path())
        .filter(|p| {
            p.is_file()
                && p.file_name().and_then(|n| n.to_str()).is_some_and(|n| {
                    n.starts_with(ROOT_PLUGIN_FILE_PREFIX) && is_plugin_file(Path::new(n))
                })
        })
        .collect();
    plugin_files.sort();
    plugin_files
}

/// The plugin files in a plugin directory, sorted.
fn plugin_files_in_dir(dir: &Path) -> Vec<PathBuf> {
    let Ok(entries) = std::fs::read_dir(dir) else {
        return Vec::new();
    };
    let mut plugin_files: Vec<PathBuf> = entries
        .filter_map(Result::ok)
        .map(|e| e.path())
        .filter(|p| p.is_file() && is_plugin_file(p))
        .collect();
    plugin_files.sort();
    plugin_files
}

/// Whether the loader reads `path` from one of its default plugin
/// locations: a `fallow-plugin-*` file, or a file in a `.fallow/plugins/`
/// directory. A file that the `plugins` config key names can have any name.
#[must_use]
pub fn is_default_external_plugin_file(path: &Path) -> bool {
    if !is_plugin_file(path) {
        return false;
    }
    let name_matches = path
        .file_name()
        .and_then(|name| name.to_str())
        .is_some_and(|name| name.starts_with(ROOT_PLUGIN_FILE_PREFIX));
    let parent = path.parent();
    let in_plugins_dir = parent
        .and_then(Path::file_name)
        .is_some_and(|name| name == DEFAULT_PLUGINS_DIR_NAME)
        && parent
            .and_then(Path::parent)
            .and_then(Path::file_name)
            .is_some_and(|name| name == ".fallow");
    name_matches || in_plugins_dir
}

/// The files that [`discover_external_plugins`] can read for a project, in
/// the order it reads them. A `plugins` entry that is not a directory is
/// listed also when it does not exist, so that a caller can see it appear.
/// The list does not apply the project-root check of the loader, so it can
/// hold a file that the loader skips.
#[must_use]
pub fn external_plugin_source_files(root: &Path, config_plugin_paths: &[String]) -> Vec<PathBuf> {
    let mut files = Vec::new();
    for path_str in config_plugin_paths {
        let path = root.join(path_str);
        if path.is_dir() {
            files.extend(plugin_files_in_dir(&path));
        } else {
            files.push(path);
        }
    }
    files.extend(plugin_files_in_dir(
        &root.join(".fallow").join(DEFAULT_PLUGINS_DIR_NAME),
    ));
    files.extend(root_plugin_files(root));
    files
}

/// Check if a path resolves within the canonical root (follows symlinks).
#[expect(
    clippy::redundant_pub_crate,
    reason = "this module is glob re-exported from lib.rs, so `pub` would leak this helper into the public API; pub(crate) is the minimal widening for the rule-pack loader"
)]
pub(crate) fn is_within_root(path: &Path, canonical_root: &Path) -> bool {
    let canonical = dunce::canonicalize(path).unwrap_or_else(|_| path.to_path_buf());
    canonical.starts_with(canonical_root)
}

fn load_plugins_from_dir(
    dir: &Path,
    canonical_root: &Path,
    plugins: &mut Vec<ExternalPluginDef>,
    seen: &mut rustc_hash::FxHashSet<String>,
) {
    for path in plugin_files_in_dir(dir) {
        load_plugin_file(&path, canonical_root, plugins, seen);
    }
}

fn load_plugin_file(
    path: &Path,
    canonical_root: &Path,
    plugins: &mut Vec<ExternalPluginDef>,
    seen: &mut rustc_hash::FxHashSet<String>,
) {
    if !is_within_root(path, canonical_root) {
        tracing::warn!(
            "plugin file '{}' resolves outside project root (symlink?), skipping",
            path.display()
        );
        return;
    }

    let Some(format) = PluginFormat::from_path(path) else {
        tracing::warn!(
            "unsupported plugin file extension for {}, expected .toml, .json, or .jsonc",
            path.display()
        );
        return;
    };

    let Some(content) = read_plugin_file(path) else {
        return;
    };

    if let Some(plugin) = parse_plugin(&content, &format, path) {
        push_plugin_if_unique(plugin, path, plugins, seen);
    }
}

fn read_plugin_file(path: &Path) -> Option<String> {
    match std::fs::read_to_string(path) {
        Ok(content) => Some(content),
        Err(e) => {
            tracing::warn!(
                "failed to read external plugin file {}: {e}",
                path.display()
            );
            None
        }
    }
}

fn push_plugin_if_unique(
    plugin: ExternalPluginDef,
    path: &Path,
    plugins: &mut Vec<ExternalPluginDef>,
    seen: &mut rustc_hash::FxHashSet<String>,
) {
    if plugin.name.is_empty() {
        tracing::warn!(
            "external plugin in {} has an empty name, skipping",
            path.display()
        );
        return;
    }

    if seen.insert(plugin.name.clone()) {
        plugins.push(plugin);
    } else {
        tracing::warn!(
            "duplicate external plugin '{}' in {}, skipping",
            plugin.name,
            path.display()
        );
    }
}

#[cfg(test)]
mod tests;