axe-ir 0.1.0

//! Intermediate representation for the AXE (Agent eXtension Engine) spec.
//!
//! The IR captures the semantic core of agent extension definitions:
//! instruction content, activation conditions, tool requirements,
//! hook bindings, and variable references.
//!
//! See <https://github.com/claylo/axe> for the full spec.

#![forbid(unsafe_code)]

/// AXE specification version this IR targets.
pub const SPEC_VERSION: &str = "1.0";

/// A parsed agent extension in platform-neutral form.
#[derive(Debug, Clone)]
pub struct Extension {
    /// Required metadata.
    pub meta: Meta,
    /// How and when this extension activates.
    pub activation: Option<Activation>,
    /// Capabilities this extension requires from the host platform.
    pub capabilities: Vec<Capability>,
    /// Markdown body containing agent instructions.
    pub content: String,
}

/// Required extension metadata.
#[derive(Debug, Clone)]
pub struct Meta {
    /// Extension name (`[a-z0-9-]`, max 64 chars).
    pub name: String,
    /// Human-readable description (max 1024 chars).
    pub description: String,
    /// AXE spec version the author wrote against.
    pub axe_version: String,
    /// Extension's own version (semver, optional).
    pub version: Option<String>,
}

/// Activation conditions for the extension.
#[derive(Debug, Clone)]
pub struct Activation {
    pub mode: ActivationMode,
    pub patterns: Vec<String>,
}

/// How the extension decides to activate.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ActivationMode {
    Always,
    Glob,
    ModelDecision,
    Manual,
}

/// Capabilities an extension may require.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Capability {
    ToolUse,
    FileRead,
    FileEdit,
    ShellExec,
    WebSearch,
    Hook(HookEvent),
    VariableSub,
    Subagent,
    McpServer,
}

/// Abstract hook events, mapped to vendor-specific names by backends.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HookEvent {
    SessionStart,
    SessionEnd,
    PreTool,
    PostTool,
    UserPrompt,
    PreCompact,
    SubagentStart,
    SubagentStop,
    Custom(String),
}

/// Diagnostic emitted during compilation.
#[derive(Debug, Clone)]
pub struct Diagnostic {
    pub level: DiagnosticLevel,
    /// Target platform (e.g., "cursor").
    pub target: String,
    /// What capability or feature is affected.
    pub capability: String,
    /// Human-readable explanation.
    pub message: String,
}

/// Severity of a compilation diagnostic.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DiagnosticLevel {
    /// Informational — no action needed.
    Info,
    /// Feature will be shimmed or degraded.
    Warning,
    /// Feature cannot be represented on target.
    Error,
}