mdforge 0.1.0

Define, validate, and render typed Markdown extensions for LLM-generated content.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112

use std::collections::{HashMap, HashSet};

use crate::{ast::ArgSpec, BlockNode, Diagnostic, Document, InlineExt, VNode};

mod args;
mod builder;
mod eval;
mod html;
mod parse;
mod render;
mod signature;
mod validate;

pub use builder::ForgeBuilder;
pub use html::HtmlRenderer;

/// Renderer used by [`Forge::render_dom`] to map extensions to [`VNode`]s.
pub trait DomRenderer {
    /// Render a block extension with already-rendered child nodes.
    fn render_block(&self, block: &BlockNode, ctx: &EvalContext, children: Vec<VNode>) -> VNode;

    /// Render an inline extension.
    fn render_inline(&self, inline: &InlineExt, ctx: &EvalContext) -> VNode;
}

/// Runtime values used by the evaluation phase.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct EvalContext {
    /// Allowed values for `ArgType::DynamicEnum`, keyed by dynamic enum name.
    pub dynamic_values: HashMap<String, HashSet<String>>,
}

/// Registered block extension specification.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct BlockSpec {
    /// Block name.
    pub name: String,
    /// Argument specifications in registration order.
    pub args: Vec<(String, ArgSpec)>,
    /// Whether the block body is intended to contain Markdown.
    pub body_markdown: bool,
}

/// Registered inline extension specification.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct InlineSpec {
    /// Inline name.
    pub name: String,
    /// Argument specifications in registration order.
    pub args: Vec<(String, ArgSpec)>,
}

/// Compiled mdforge schema and processing pipeline.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Forge {
    blocks: Vec<BlockSpec>,
    inlines: Vec<InlineSpec>,
}

impl Forge {
    /// Start building a [`Forge`] schema.
    pub fn builder() -> ForgeBuilder {
        ForgeBuilder::default()
    }

    /// Parse source text into a [`Document`].
    pub fn parse(&self, input: &str) -> Result<Document, Vec<Diagnostic>> {
        parse::parse_document(self, input)
    }

    /// Validate parsed blocks, inlines, required arguments, and static types.
    pub fn validate(&self, doc: &Document) -> Result<(), Vec<Diagnostic>> {
        validate::validate_document(self, doc)
    }

    /// Evaluate runtime-dependent constraints such as dynamic enums.
    pub fn eval(
        &self,
        doc: &Document,
        dynamic_ctx: &EvalContext,
    ) -> Result<EvalContext, Vec<Diagnostic>> {
        eval::eval_document(self, doc, dynamic_ctx)
    }

    /// Render a document into a virtual DOM using a custom renderer.
    pub fn render_dom(
        &self,
        doc: &Document,
        ctx: &EvalContext,
        renderer: &dyn DomRenderer,
    ) -> Result<Vec<VNode>, Vec<Diagnostic>> {
        render::render_document(self, doc, ctx, renderer)
    }

    /// Generate a compact syntax signature for prompts or documentation.
    pub fn signature(&self) -> String {
        signature::build_signature(self)
    }

    /// Render a document to HTML using pulldown-cmark for normal Markdown.
    pub fn render_html(
        &self,
        doc: &Document,
        ctx: &EvalContext,
        renderer: &dyn HtmlRenderer,
    ) -> Result<String, Vec<Diagnostic>> {
        html::render_html_document(self, doc, ctx, renderer)
    }
}

#[cfg(test)]
mod tests;