bext-plugin-api 0.2.0

//! Source-code transform plugin trait for the build pipeline.
//! Plugins can rewrite file contents at compile time (e.g. macro expansion,
//! code injection) and run in priority order alongside built-in transforms.

use crate::types::transform_priority;

/// Context provided to transform plugins (read-only view of build state).
#[derive(Debug, Clone)]
pub struct TransformContext {
    /// Current NODE_ENV value.
    pub node_env: String,
    /// NEXT_PUBLIC_ environment variables as (key, value) pairs.
    pub env_vars: Vec<(String, String)>,
}

/// A plugin that hooks into the source-code transform pipeline.
///
/// **Compile-time only** — no WASM overhead on every file.
///
/// Built-in transforms run at priorities 100–700. Plugin transforms default
/// to priority 1000 (after all built-ins). Lower priority runs first.
pub trait TransformPlugin: Send + Sync {
    /// Unique identifier (e.g., `"my-macro-expansion"`).
    fn name(&self) -> &str;

    /// Execution priority. Lower runs first. Default: 1000 (after built-ins).
    fn priority(&self) -> u32 {
        transform_priority::PLUGIN_DEFAULT
    }

    /// Return `true` if this plugin should process the file at `path`.
    /// Called before `transform()` to skip unnecessary work.
    fn matches(&self, path: &str, source: &str) -> bool;

    /// Transform the source code.
    ///
    /// Returns `Some(new_source)` if modified, `None` if unchanged.
    /// Receives the current source which may already be modified by
    /// earlier transforms in the pipeline.
    fn transform(&self, source: &str, path: &str, ctx: &TransformContext) -> Option<String>;
}