satteri_plugin_api/
plugin.rs

1use crate::context::PluginContext;
2use crate::typed_nodes::*;
3use satteri_arena::Arena;
4use satteri_mdast::MdastNodeType;
5
6/// Metadata about a plugin.
7#[derive(Debug, Clone)]
8pub struct PluginMeta {
9    pub name: &'static str,
10    pub version: Option<&'static str>,
11    pub description: Option<&'static str>,
12}
13
14impl PluginMeta {
15    pub fn new(name: &'static str) -> Self {
16        Self {
17            name,
18            version: None,
19            description: None,
20        }
21    }
22}
23
24/// The result of a visitor method — either no change, or a replacement.
25pub enum VisitResult {
26    /// No structural change (plugin may have written to data_map via ctx)
27    NoChange,
28    /// Replace this node with a new one
29    Replace(crate::commands::NewNode),
30    /// Remove this node
31    Remove,
32}
33
34impl VisitResult {
35    pub fn no_change() -> Self {
36        Self::NoChange
37    }
38    pub fn replace(node: crate::commands::NewNode) -> Self {
39        Self::Replace(node)
40    }
41    pub fn remove() -> Self {
42        Self::Remove
43    }
44}
45
46/// The Rust plugin trait.
47///
48/// Implement only the visitor methods you need. Default implementations
49/// return NoChange (no-op) so unimplemented visitors have zero overhead.
50pub trait Plugin: Send + Sync {
51    fn meta(&self) -> PluginMeta;
52
53    /// Called once before any files are processed.
54    fn init(&mut self) {}
55
56    /// Called before each file.
57    fn before(&mut self, _arena: &Arena, _ctx: &mut PluginContext) {}
58
59    /// Called after each file.
60    fn after(&mut self, _arena: &Arena, _ctx: &mut PluginContext) {}
61
62    // ── Node visitors — implement only what you need ──────────────────────────
63
64    fn visit_heading(&mut self, _node: &Heading, _ctx: &mut PluginContext) -> VisitResult {
65        VisitResult::NoChange
66    }
67    fn visit_paragraph(&mut self, _node: &Paragraph, _ctx: &mut PluginContext) -> VisitResult {
68        VisitResult::NoChange
69    }
70    fn visit_text(&mut self, _node: &Text, _ctx: &mut PluginContext) -> VisitResult {
71        VisitResult::NoChange
72    }
73    fn visit_link(&mut self, _node: &Link, _ctx: &mut PluginContext) -> VisitResult {
74        VisitResult::NoChange
75    }
76    fn visit_image(&mut self, _node: &Image, _ctx: &mut PluginContext) -> VisitResult {
77        VisitResult::NoChange
78    }
79    fn visit_code(&mut self, _node: &Code, _ctx: &mut PluginContext) -> VisitResult {
80        VisitResult::NoChange
81    }
82    fn visit_list(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
83        VisitResult::NoChange
84    }
85    fn visit_list_item(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
86        VisitResult::NoChange
87    }
88    fn visit_blockquote(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
89        VisitResult::NoChange
90    }
91    fn visit_emphasis(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
92        VisitResult::NoChange
93    }
94    fn visit_strong(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
95        VisitResult::NoChange
96    }
97    fn visit_inline_code(&mut self, _node: &Text, _ctx: &mut PluginContext) -> VisitResult {
98        VisitResult::NoChange
99    }
100    fn visit_html(&mut self, _node: &Text, _ctx: &mut PluginContext) -> VisitResult {
101        VisitResult::NoChange
102    }
103    fn visit_table(&mut self, _node: &NodeView, _ctx: &mut PluginContext) -> VisitResult {
104        VisitResult::NoChange
105    }
106
107    /// Optional: full arena access for wholesale rewrites. Return None to leave unchanged.
108    fn transform_root(&mut self, _arena: &Arena, _ctx: &mut PluginContext) -> Option<Arena> {
109        None
110    }
111}
112
113/// A generic node view for nodes that don't have type-specific fields.
114pub struct NodeView<'a> {
115    pub(crate) node_id: u32,
116    pub(crate) arena: &'a Arena,
117}
118
119impl<'a> NodeView<'a> {
120    pub fn id(&self) -> u32 {
121        self.node_id
122    }
123    pub fn children(&self) -> &[u32] {
124        self.arena.get_children(self.node_id)
125    }
126    pub fn position(&self) -> NodePosition {
127        NodePosition::from_node(self.arena.get_node(self.node_id))
128    }
129    pub fn node_type(&self) -> MdastNodeType {
130        let raw = self.arena.get_node(self.node_id).node_type;
131        MdastNodeType::from_u8(raw).unwrap_or(MdastNodeType::Root)
132    }
133}
satteri_plugin_api/plugin.rs

satteri_plugin_api/
plugin.rs
