Skip to main content

decl_lang/
api.rs

1//! The high-level API of the crate: the operations the `decl` command line
2//! offers, in the same vocabulary — `evaluate` binds inputs and returns
3//! outputs, `check`, `validate`, `evaluate_source`, `format_source` — for
4//! programs that would otherwise assemble parser, checker, and engine by
5//! hand (those modules are public too). The npm package and the Python
6//! package offer the same functions with the same semantics.
7use indexmap::IndexMap;
8use std::fmt;
9use std::path::PathBuf;
10
11use crate::checker::check_module;
12use crate::cli::{check_files, file_tag, open_universe};
13use crate::module::{run_universe, Bind, Module};
14use crate::parse::parse_source;
15use crate::pipeline::run_pipeline;
16pub use crate::pipeline::{evaluate_source, Report};
17use crate::render::{absolute, declared_form, emit_root, resolve_in, Emission, Emitted, Form};
18use crate::semantics::{read_json, Diag};
19use crate::yaml::{is_yaml_path, read_yaml, to_json as json_text, to_yaml as yaml_text};
20use std::rc::Rc;
21
22/// One diagnostic, in the report's field order (§12.2).
23#[derive(Clone, Debug, PartialEq, Eq)]
24pub struct Diagnostic {
25    /// the file the diagnostic is reported against: the entry module by the path given, another module by its absolute path
26    pub file: String,
27    /// the diagnostic code (§12), when the finding carries one
28    pub code: Option<String>,
29    /// the constraint's stable id (`Type.name`), for an assertion
30    pub id: Option<String>,
31    /// `error`, `warn`, or `info`
32    pub severity: String,
33    /// the message, rendered
34    pub message: String,
35    /// the canonical path of the value the finding concerns (§7.2); empty for a module-level finding
36    pub path: String,
37    /// source span, 1-based (file, line, col); present for compile-time diagnostics (§12.2)
38    pub location: Option<(String, usize, usize)>,
39}
40
41/// An operation failed; `diagnostics` carries the report (empty for a usage
42/// error such as an unknown input or root).
43#[derive(Clone, Debug)]
44pub struct DeclError {
45    /// the first diagnostic's message, or the usage error
46    pub message: String,
47    /// the report (§12.2), in canonical order; empty for a usage error
48    pub diagnostics: Vec<Diagnostic>,
49}
50impl fmt::Display for DeclError {
51    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
52        f.write_str(&self.message)
53    }
54}
55impl std::error::Error for DeclError {}
56
57/// A document to bind to an input: the path of a JSON file, or its JSON text.
58#[derive(Clone, Debug)]
59pub enum Document {
60    /// a JSON or YAML file, by path (YAML by its extension)
61    File(PathBuf),
62    /// JSON text
63    Json(String),
64}
65
66/// What `evaluate` binds and returns.
67#[derive(Clone, Debug, Default)]
68pub struct EvaluateOptions {
69    /// documents to bind, by input name
70    pub inputs: Vec<(String, Document)>,
71    /// the roots to return — outputs, or inputs bound here or demanded
72    /// through their fallback; empty: the entry module's exported outputs (§5.5)
73    pub outputs: Vec<String>,
74}
75
76fn tagged(file: &str, d: &Diag) -> Diagnostic {
77    Diagnostic {
78        file: file.to_string(),
79        code: d.code.clone(),
80        id: d.id.clone(),
81        severity: d.severity.clone(),
82        message: d.message.clone(),
83        path: d.path.clone(),
84        location: d
85            .loc
86            .as_ref()
87            .map(|l| (file.to_string(), l.sl + 1, l.sc + 1)),
88    }
89}
90fn fail<T>(fallback: &str, diagnostics: Vec<Diagnostic>) -> Result<T, DeclError> {
91    let message = diagnostics
92        .first()
93        .map(|d| d.message.clone())
94        .unwrap_or_else(|| fallback.to_string());
95    Err(DeclError {
96        message,
97        diagnostics,
98    })
99}
100
101// the documents to bind, each to the module that declares its input (§10)
102fn bind_inputs(
103    modules: &[Rc<Module>],
104    file: &str,
105    inputs: &[(String, Document)],
106) -> Result<Vec<Bind>, DeclError> {
107    let mut binds = vec![];
108    for (name, doc) in inputs {
109        let Some(module) = modules
110            .iter()
111            .find(|m| m.env.inputs.borrow().contains_key(name))
112        else {
113            return Err(DeclError {
114                message: format!("no input named {name}"),
115                diagnostics: vec![],
116            });
117        };
118        let e6004 = |message: String| Diagnostic {
119            file: file.to_string(),
120            code: Some("E6004".into()),
121            id: None,
122            severity: "error".into(),
123            location: None,
124            message,
125            path: name.clone(),
126        };
127        let (text, place) = match doc {
128            Document::File(p) => match std::fs::read_to_string(p) {
129                Ok(t) => (t, p.display().to_string()),
130                Err(_) => {
131                    return fail(
132                        "",
133                        vec![e6004(format!(
134                            "bound document cannot be read: {}",
135                            p.display()
136                        ))],
137                    )
138                }
139            },
140            Document::Json(t) => (t.clone(), name.clone()),
141        };
142        // a file is YAML by its extension (docs/tooling/05_render.md §2)
143        let yaml = matches!(doc, Document::File(p) if is_yaml_path(&p.display().to_string()));
144        let raw = if yaml {
145            match read_yaml(&text) {
146                Ok(v) => v,
147                Err(e) => {
148                    return fail(
149                        "",
150                        vec![e6004(format!(
151                            "bound document is not well-formed YAML: {place}: {e}"
152                        ))],
153                    )
154                }
155            }
156        } else {
157            match read_json(&text) {
158                Ok(v) => v,
159                Err(_) => {
160                    return fail(
161                        "",
162                        vec![e6004(format!(
163                            "bound document is not well-formed JSON: {place}"
164                        ))],
165                    )
166                }
167            }
168        };
169        binds.push(Bind {
170            module: Some(module.clone()),
171            input: name.clone(),
172            raw,
173        });
174    }
175    Ok(binds)
176}
177
178/// Evaluate a module: bind the input documents, run the pipeline, and return
179/// the requested roots' documents (canonical JSON text) by name. Fails with
180/// the diagnostics on any error-severity outcome.
181pub fn evaluate(path: &str, opts: &EvaluateOptions) -> Result<IndexMap<String, String>, DeclError> {
182    let r = open_universe(path);
183    let Some(entry) = r.entry.clone() else {
184        return fail(
185            &format!("{path}: cannot be loaded"),
186            r.diags.iter().map(|d| tagged(path, d)).collect(),
187        );
188    };
189    if !r.diags.is_empty() {
190        return fail("", r.diags.iter().map(|d| tagged(path, d)).collect());
191    }
192    let checks: Vec<Diagnostic> = r
193        .modules
194        .iter()
195        .flat_map(|m| {
196            let tag = file_tag(path, Some(entry.path.as_path()), &m.path);
197            check_module(&m.decls, Some(m.env.clone()), None)
198                .iter()
199                .map(|d| tagged(&tag, d))
200                .collect::<Vec<_>>()
201        })
202        .collect();
203    if checks.iter().any(|d| d.severity == "error") {
204        return fail("", checks);
205    }
206    let binds = bind_inputs(&r.modules, path, &opts.inputs)?;
207    let (eng, diags) = run_universe(&r.modules, &entry, binds);
208    let report: Vec<Diagnostic> = diags.iter().map(|d| tagged(path, d)).collect();
209    if report.iter().any(|d| d.severity == "error") {
210        return fail("", report);
211    }
212    let names: Vec<String> = if opts.outputs.is_empty() {
213        entry
214            .decls
215            .iter()
216            .filter(|d| d.exported)
217            .filter_map(|d| match &d.body {
218                crate::ast::DeclBody::Output { name, .. } => Some(name.clone()),
219                _ => None,
220            })
221            .collect()
222    } else {
223        opts.outputs.clone()
224    };
225    let mut out = IndexMap::new();
226    for n in &names {
227        let Some(v) = entry.env.root(n) else {
228            return Err(DeclError {
229                message: format!("no root named {n}"),
230                diagnostics: report,
231            });
232        };
233        out.insert(n.clone(), eng.serialize(&v, n, false));
234    }
235    Ok(out)
236}
237
238/// a template for `render`: the path of a template file, or its text
239#[derive(Debug, Clone)]
240pub enum TemplateSource {
241    /// a template file, by path
242    File(PathBuf),
243    /// the template's text
244    Text(String),
245}
246/// the options of `render` (docs/tooling/05_render.md §7)
247#[derive(Debug, Clone, Default)]
248pub struct RenderOptions {
249    /// documents to bind, by input name
250    pub inputs: Vec<(String, Document)>,
251    /// the roots to return; empty: the entry module's exported outputs
252    pub outputs: Vec<String>,
253    /// `Some(true)` for YAML, `Some(false)` for JSON: overrides every root's declared format
254    pub yaml: Option<bool>,
255    /// the layout: overrides every root's declared indent
256    pub indent: Option<usize>,
257    /// templates by root name (`"*"` for every root without one of its own)
258    pub templates: Vec<(String, TemplateSource)>,
259}
260/// a rendered root: one text, or the files of a fan-out root by path
261#[derive(Debug, Clone, PartialEq)]
262pub enum Rendered {
263    /// one text
264    Text(String),
265    /// the files of a fan-out root, by path, in element order
266    Files(IndexMap<String, String>),
267}
268
269/// Render a module's roots in the forms their `@render` annotations declare
270/// (docs/tooling/05_render.md), with the options as overrides: bind the
271/// input documents, evaluate, and return each root's text — or, for a
272/// fan-out root, its files by path. Nothing is written to disk. Fails with
273/// the diagnostics on any error-severity outcome.
274pub fn render(path: &str, opts: &RenderOptions) -> Result<IndexMap<String, Rendered>, DeclError> {
275    let r = open_universe(path);
276    let Some(entry) = r.entry.clone() else {
277        return fail(
278            &format!("{path}: cannot be loaded"),
279            r.diags.iter().map(|d| tagged(path, d)).collect(),
280        );
281    };
282    if !r.diags.is_empty() {
283        return fail("", r.diags.iter().map(|d| tagged(path, d)).collect());
284    }
285    let checks: Vec<Diagnostic> = r
286        .modules
287        .iter()
288        .flat_map(|m| {
289            let tag = file_tag(path, Some(entry.path.as_path()), &m.path);
290            check_module(&m.decls, Some(m.env.clone()), None)
291                .iter()
292                .map(|d| tagged(&tag, d))
293                .collect::<Vec<_>>()
294        })
295        .collect();
296    if checks.iter().any(|d| d.severity == "error") {
297        return fail("", checks);
298    }
299    let binds = bind_inputs(&r.modules, path, &opts.inputs)?;
300    let (eng, diags) = run_universe(&r.modules, &entry, binds);
301    let report: Vec<Diagnostic> = diags.iter().map(|d| tagged(path, d)).collect();
302    if report.iter().any(|d| d.severity == "error") {
303        return fail("", report);
304    }
305    let names: Vec<String> = if opts.outputs.is_empty() {
306        entry
307            .decls
308            .iter()
309            .filter(|d| d.exported)
310            .filter_map(|d| match &d.body {
311                crate::ast::DeclBody::Output { name, .. } => Some(name.clone()),
312                _ => None,
313            })
314            .collect()
315    } else {
316        opts.outputs.clone()
317    };
318    let texts: std::cell::RefCell<std::collections::HashMap<String, Option<String>>> =
319        std::cell::RefCell::new(std::collections::HashMap::new());
320    let read_tpl = |abs: &str| -> Option<String> {
321        if !texts.borrow().contains_key(abs) {
322            let t = std::fs::read_to_string(abs).ok();
323            texts.borrow_mut().insert(abs.to_string(), t);
324        }
325        texts.borrow().get(abs).cloned().flatten()
326    };
327    let e7003 = |file: &str, n: &str| -> DeclError {
328        DeclError {
329            message: "template cannot be read".into(),
330            diagnostics: vec![Diagnostic {
331                file: file.to_string(),
332                code: Some("E7003".into()),
333                id: None,
334                severity: "error".into(),
335                message: "template cannot be read".into(),
336                path: n.to_string(),
337                location: None,
338            }],
339        }
340    };
341    let mut out: IndexMap<String, Rendered> = IndexMap::new();
342    for n in &names {
343        let Some(v) = entry.env.root(n) else {
344            return Err(DeclError {
345                message: format!("no root named {n}"),
346                diagnostics: report,
347            });
348        };
349        let found = r.modules.iter().find_map(|m| {
350            m.decls
351                .iter()
352                .find(|d| matches!(&d.body, crate::ast::DeclBody::Output { name, .. } if name == n))
353                .map(|d| (d, m))
354        });
355        let form = match found {
356            Some((d, _)) => match declared_form(d) {
357                Ok(f) => f,
358                Err(m) => {
359                    return fail(
360                        "",
361                        vec![Diagnostic {
362                            file: path.to_string(),
363                            code: Some("E7004".into()),
364                            id: None,
365                            severity: "error".into(),
366                            message: m,
367                            path: n.clone(),
368                            location: None,
369                        }],
370                    )
371                }
372            },
373            None => Form::default(),
374        };
375        let src = opts
376            .templates
377            .iter()
378            .find(|(k, _)| k == n)
379            .or_else(|| opts.templates.iter().find(|(k, _)| k == "*"))
380            .map(|(_, t)| t);
381        let template: Option<(String, String, String)> = match src {
382            Some(TemplateSource::File(p)) => {
383                let given = p.to_string_lossy().to_string();
384                let abs = absolute(&given);
385                let Some(text) = read_tpl(&abs) else {
386                    return Err(e7003(&given, n));
387                };
388                Some((given, text, parent_of(&abs)))
389            }
390            Some(TemplateSource::Text(t)) => {
391                let cwd = std::env::current_dir()
392                    .map(|p| p.to_string_lossy().to_string())
393                    .unwrap_or_else(|_| ".".into());
394                Some(("<text>".into(), t.clone(), cwd))
395            }
396            None => match &form.template {
397                Some(t) => {
398                    let dir = found
399                        .and_then(|(_, m)| m.path.parent().map(|p| p.to_string_lossy().to_string()))
400                        .unwrap_or_else(|| ".".into());
401                    let abs = resolve_in(&dir, t);
402                    let Some(text) = read_tpl(&abs) else {
403                        return Err(e7003(t, n));
404                    };
405                    Some((t.clone(), text, parent_of(&abs)))
406                }
407                None => None,
408            },
409        };
410        match emit_root(&Emission {
411            eng: eng.clone(),
412            menv: entry.env.clone(),
413            root_name: n.clone(),
414            value: v,
415            form,
416            yaml: opts.yaml,
417            indent: opts.indent,
418            template,
419            read_template: &read_tpl,
420        }) {
421            Ok(Emitted::One(text)) => {
422                out.insert(n.clone(), Rendered::Text(text));
423            }
424            Ok(Emitted::Many(files)) => {
425                out.insert(n.clone(), Rendered::Files(files.into_iter().collect()));
426            }
427            Err(e) => {
428                return fail(
429                    "",
430                    vec![tagged(e.file.as_deref().unwrap_or(path), &e.diag())],
431                )
432            }
433        }
434    }
435    Ok(out)
436}
437fn parent_of(p: &str) -> String {
438    std::path::Path::new(p)
439        .parent()
440        .map(|d| d.to_string_lossy().to_string())
441        .unwrap_or_else(|| ".".into())
442}
443
444/// Parse and statically check entry files (module-aware); empty means clean.
445pub fn check(paths: &[&str]) -> Vec<Diagnostic> {
446    let owned: Vec<String> = paths.iter().map(|p| p.to_string()).collect();
447    check_files(&owned)
448        .iter()
449        .map(|(file, d)| tagged(file, d))
450        .collect()
451}
452
453/// Validate a file: static checks, then evaluation with the input documents
454/// bound; returns every diagnostic (all severities). Fails when the file
455/// does not parse.
456pub fn validate(path: &str, inputs: &[(String, Document)]) -> Result<Vec<Diagnostic>, DeclError> {
457    let src = std::fs::read_to_string(path).map_err(|_| DeclError {
458        message: format!("{path}: cannot be read"),
459        diagnostics: vec![],
460    })?;
461    let parsed = parse_source(&src);
462    if !parsed.errors.is_empty() {
463        return Err(DeclError {
464            message: format!("{path}: {} parse error(s)", parsed.errors.len()),
465            diagnostics: vec![],
466        });
467    }
468    let checks: Vec<Diagnostic> = check_module(&parsed.decls, None, None)
469        .iter()
470        .map(|d| tagged(path, d))
471        .collect();
472    if checks.iter().any(|d| d.severity == "error") {
473        return Ok(checks);
474    }
475    // a warning of the checks (W0001) is returned beside the run's diagnostics
476    let mut all = checks;
477    if !inputs.is_empty() {
478        let r = open_universe(path);
479        let Some(entry) = r.entry.clone() else {
480            return fail(
481                &format!("{path}: cannot be loaded"),
482                r.diags.iter().map(|d| tagged(path, d)).collect(),
483            );
484        };
485        let binds = bind_inputs(&r.modules, path, inputs)?;
486        let (_, diags) = run_universe(&r.modules, &entry, binds);
487        all.extend(diags.iter().map(|d| tagged(path, d)));
488        return Ok(all);
489    }
490    all.extend(
491        run_pipeline(&parsed.decls)
492            .diags
493            .iter()
494            .map(|d| tagged(path, d)),
495    );
496    Ok(all)
497}
498
499/// The canonical formatting of a source text; fails when it does not parse.
500pub fn format_source(text: &str) -> Result<String, DeclError> {
501    crate::fmt::format(text).map_err(|message| DeclError {
502        message,
503        diagnostics: vec![],
504    })
505}
506
507// a document's text (canonical JSON) as the reader's shape; the text is the
508// library's document form, so its number texts pass through exactly
509fn raw_of(text: &str) -> Result<crate::semantics::Value, DeclError> {
510    read_json(text).map_err(|_| DeclError {
511        message: "not well-formed JSON".into(),
512        diagnostics: vec![],
513    })
514}
515
516/// The JSON text of a document given as JSON text: canonical for indent 0,
517/// laid out with `indent` spaces per level otherwise (docs/tooling/05_render.md §4.1).
518pub fn to_json(text: &str, indent: usize) -> Result<String, DeclError> {
519    Ok(json_text(&raw_of(text)?, indent))
520}
521/// The YAML text of a document given as JSON text (docs/tooling/05_render.md §4.2), no trailing newline.
522pub fn to_yaml(text: &str, indent: usize) -> Result<String, DeclError> {
523    Ok(yaml_text(&raw_of(text)?, indent))
524}