Skip to main content

rustcmdpev_core/
lib.rs

1//! Core parsing, analysis, and rendering primitives for `rustcmdpev`.
2
3use std::error::Error;
4use std::fmt;
5
6pub mod analysis;
7pub mod constants;
8pub mod display;
9pub mod parser;
10pub mod render;
11pub mod structure;
12pub mod summary;
13pub mod testing;
14
15use parser::ParseOptions;
16use structure::data::explain::Explain;
17
18#[derive(Debug)]
19pub enum VisualizeError {
20    InvalidJson(serde_json::Error),
21    EmptyExplainArray,
22    MissingPlan,
23    InvalidPlan(String),
24}
25
26impl fmt::Display for VisualizeError {
27    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
28        match self {
29            VisualizeError::InvalidJson(err) => write!(f, "invalid JSON input: {err}"),
30            VisualizeError::EmptyExplainArray => {
31                write!(
32                    f,
33                    "top-level JSON array must contain at least one explain object"
34                )
35            }
36            VisualizeError::MissingPlan => {
37                write!(f, "first explain object must contain 'Plan' object")
38            }
39            VisualizeError::InvalidPlan(message) => write!(f, "{message}"),
40        }
41    }
42}
43
44impl Error for VisualizeError {}
45
46/// Apply analysis passes to a validated explain document.
47pub fn analyze_explain(explain: Explain) -> Explain {
48    analysis::process_all(explain)
49}
50
51/// Parse raw input and run the full validation and analysis pipeline.
52pub fn parse_and_process(input: &str) -> Result<Explain, VisualizeError> {
53    let explain = parser::parse_explain_document(input)?;
54    Ok(analyze_explain(explain))
55}
56
57/// Parse with explicit `ParseOptions` (e.g. a `--postgres-version` hint).
58pub fn parse_and_process_with(
59    input: &str,
60    options: &ParseOptions,
61) -> Result<Explain, VisualizeError> {
62    let explain = parser::parse_explain_document_with(input, options)?;
63    Ok(analyze_explain(explain))
64}
65
66/// Produce pretty rendered output without performing stdout I/O.
67pub fn render_visualization(input: &str, width: usize) -> Result<String, VisualizeError> {
68    render_visualization_with(input, render::RenderOptions::new(width))
69}
70
71/// Produce pretty rendered output using fully customised render options.
72pub fn render_visualization_with(
73    input: &str,
74    options: render::RenderOptions,
75) -> Result<String, VisualizeError> {
76    render_visualization_full(input, &ParseOptions::default(), options)
77}
78
79/// Produce pretty rendered output using both parser and render options.
80pub fn render_visualization_full(
81    input: &str,
82    parse_options: &ParseOptions,
83    render_options: render::RenderOptions,
84) -> Result<String, VisualizeError> {
85    let explain = parse_and_process_with(input, parse_options)?;
86    Ok(render::render_explain(&explain, render_options))
87}
88
89/// Legacy convenience entry point that returns the analyzed explain.
90pub fn visualize(input: String, width: usize) -> Result<Explain, VisualizeError> {
91    let explain = parse_and_process(input.as_str())?;
92    let _rendered = render::render_explain(&explain, render::RenderOptions::new(width));
93    Ok(explain)
94}