nova-cli 0.3.0

The Nova programming language: compiler, formatter, language server, package manager and documentation generator
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
113
114
115
116
117
118
119
120
121

//! `nova doc [--open] [--std]`: the documentation site (spec
//! `docs/superpowers/specs/2026-10-11-phase-3-5a-the-documentation-site-design.md`
//! §4; ADR 0034).

use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};

use anyhow::{anyhow, bail, Result};
use clap::Args;
use nova_diagnostics::{render, Severity};
use nova_doc::Failure;

use crate::project::{self, Mode};

#[derive(Args)]
pub struct DocCmd {
    /// Open the site's start page afterwards, with $BROWSER or the
    /// system's opener.
    #[arg(long)]
    open: bool,

    /// Document std alone, inside a project or not.
    #[arg(long)]
    std: bool,
}

pub fn run(cmd: DocCmd) -> Result<()> {
    let mode = project::mode(None)?;
    let documented = if cmd.std {
        nova_doc::document_std().map_err(failure)?
    } else {
        let Mode::Project { root, .. } = &mode else {
            bail!("nova doc documents a project; run it inside one, or use `nova doc --std`");
        };
        project::sync(&mode)?;
        nova_doc::document_package(root).map_err(failure)?
    };
    render::emit_all(&documented.db, &documented.warnings);
    let dir = match &mode {
        Mode::Project { target_dir, .. } => target_dir.join("doc"),
        Mode::File(_) => PathBuf::from("target").join("doc"),
    };
    let start = nova_doc::write_site(&documented.site, &dir)?;
    for broken in nova_doc::check_links(&dir) {
        eprintln!("warning: {}: broken link `{}`", broken.page, broken.link);
    }
    println!("{}", start.display());
    if cmd.open {
        open(&start);
    }
    Ok(())
}

/// A failure as the command's error, its diagnostics printed first (plan
/// decision 15).
fn failure(f: Failure) -> anyhow::Error {
    match f {
        Failure::Diagnostics { db, diagnostics } => {
            render::emit_all(&db, &diagnostics);
            let errors = diagnostics
                .iter()
                .filter(|d| d.severity == Severity::Error)
                .count();
            anyhow!(
                "could not document due to {errors} previous error{}",
                if errors == 1 { "" } else { "s" }
            )
        }
        Failure::Other(why) => anyhow!(why),
    }
}

/// Open `page` (spec §4.1; plan decision 16) with `$BROWSER` when it is
/// set, else with the system's opener. A failure is a warning.
fn open(page: &Path) {
    let page = if page.is_absolute() {
        page.to_path_buf()
    } else {
        std::env::current_dir().map_or_else(|_| page.to_path_buf(), |d| d.join(page))
    };
    let mut command = match std::env::var_os("BROWSER") {
        Some(browser) if !browser.is_empty() => Command::new(browser),
        _ => opener(),
    };
    command
        .arg(&page)
        .stdin(Stdio::null())
        .stdout(Stdio::null())
        .stderr(Stdio::null());
    match command.spawn() {
        // nova exits next and the browser outlives it; the thread only
        // reaps it if it closes first.
        Ok(mut child) => {
            std::thread::spawn(move || {
                let _ = child.wait();
            });
        }
        Err(e) => eprintln!(
            "warning: could not open a browser ({e}); the site is at {}",
            page.display()
        ),
    }
}

#[cfg(target_os = "macos")]
fn opener() -> Command {
    Command::new("open")
}

// `explorer` opens a file with its associated program. `cmd /C start`
// would read the path with cmd.exe's quoting, which Rust does not apply
// when the program is `cmd`, so a path with `&`, `^`, `|` or `%` broke.
#[cfg(windows)]
fn opener() -> Command {
    Command::new("explorer")
}

#[cfg(not(any(windows, target_os = "macos")))]
fn opener() -> Command {
    Command::new("xdg-open")
}