tw-cli 0.1.0

//! `tw.toml` — the checks this corpus wants that are not `tw`'s to make.
//!
//! ## Why there is a seam here at all
//!
//! Some questions about a corpus can only be answered by the tool that owns
//! the format they are about. Whether a site generator's navigation file
//! names pages that exist is one: the file is the generator's, its paths
//! resolve by rules the generator encodes, and a second reader of it in
//! `markdoc-lint` would be the second list this project keeps deleting.
//!
//! So `tw` does not learn those formats. It asks whoever owns them, and the
//! contract is one line: **a tool that owns a format exposes
//! `--check --json` and prints `markdoc_lint::Diagnostic` records under a
//! `diagnostics` key.** Two tools already did before this file existed —
//! `markdoc-lint --json` and `markdoc-prose --json` — so the site generator
//! joining them cost it an enum arm, not a format.
//!
//! ```toml
//! [[check.external]]
//! run = ["site-gen", "--check", "--json"]
//! ```
//!
//! Generic mechanism, corpus names the tool. Nothing here knows which site
//! generator a corpus has or what its files are called, which is what keeps
//! `tw` publishable for a corpus that has never heard of either.
//!
//! ## The programs a corpus pins
//!
//! The same file names the programs `tw` runs from a pin in
//! `.tooling/tooling-versions.json` that are not `tw`'s own -- a site
//! generator above all, which is the corpus's choice and not this tool's:
//!
//! ```toml
//! [tools.site-gen]
//! pin = "site-gen"                    # the tooling-versions.json key
//! # asset = "{pin}-{platform}.tar.gz" # the default: an archive, bin/site-gen in it
//! # env = "SITE_GEN_BIN"              # the default: a build of one's own
//! # checkout = "site-gen"             # a sibling checkout's target/release
//!
//! [preview]
//! run = "site-gen"                    # what `tw preview` runs
//! ```
//!
//! A name in `run` is a program that takes `--root <corpus root>` and then
//! `tw preview`'s arguments. A generator that has no such mode is named by
//! a command line instead -- `run = ["npm", "run", "preview", "--"]` --
//! which runs as written, from the corpus root, with `tw preview`'s
//! arguments after it; its first word is resolved the same way.
//!
//! A `[[check.external]]` command that names one of them runs the pinned
//! release, as `tw preview` does, rather than whatever is on `PATH`.
//!
//! ## Why a file of its own
//!
//! Not `markdoc-lint.toml`. That file is read by the language server, and a
//! language server that spawned a site generator because a config file told
//! it to would be a surprising thing to install. `markdoc-lint` is a
//! library about documents; running other programs is a decision only the
//! command-line tool is in a position to make, so it is configured where
//! that tool reads.

use markdoc_lint::{Diagnostic, Severity};
use serde::Deserialize;
use std::collections::BTreeMap;
use std::path::{Path, PathBuf};
use std::process::Command;

use crate::tools;

pub const CONFIG_FILENAME: &str = "tw.toml";

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(deny_unknown_fields, default)]
pub struct Config {
    pub check: CheckConfig,
    /// Pins in `tooling-versions.json` whose archives carry `tw-*` commands.
    ///
    /// `tw foo` resolves `tw-foo` on `PATH`, and a writer's `PATH` is not
    /// something `tw setup` should be editing. Naming the pin here instead
    /// lets `tw setup` fetch it and `tw` look inside it — without `tw`
    /// learning which corpus's commands it carries, which is the same shape
    /// `[[check.external]]` has.
    ///
    /// The archive has to be named `<pin>-<platform>.tar.gz` with its
    /// binaries in `bin/`, which is what every other pinned archive here
    /// already does.
    pub extensions: Vec<String>,
    /// Programs `tw` runs from a pin: `[tools.<name>]`.
    pub tools: BTreeMap<String, ToolConfig>,
    /// What `tw preview` runs.
    pub preview: PreviewConfig,
}

/// A program `tw` runs from a pin, as `[tools.<name>]` declares it.
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ToolConfig {
    /// The key of `.tooling/tooling-versions.json` whose release carries it.
    pub pin: String,
    /// The asset's name: `{platform}`, `{exe}` and `{pin}` filled in. An
    /// archive (`.tar.gz`, `.tgz`, `.zip`) holds the program in `bin/`.
    /// Default `{pin}-{platform}.tar.gz`, the convention every archived pin
    /// here follows.
    pub asset: Option<String>,
    /// The variable that points at a build of one's own instead. Default:
    /// the name upper-cased, `-` as `_`, then `_BIN`.
    pub env: Option<String>,
    /// The sibling checkout whose `target/release/` holds a local build.
    pub checkout: Option<String>,
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(deny_unknown_fields, default)]
pub struct PreviewConfig {
    /// What `tw preview` runs: a program, given `--root` and the arguments
    /// `tw preview` was given, or a command line run as written from the
    /// corpus root. Either way the program is a name under `[tools]`, a tool
    /// `tw` pins itself, or one on `PATH`.
    pub run: Option<PreviewRun>,
}

#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(untagged)]
pub enum PreviewRun {
    /// `run = "site-gen"`: `site-gen --root <corpus root> <args>`.
    Program(String),
    /// `run = ["npm", "run", "preview", "--"]`: as written, then `<args>`,
    /// in the corpus root.
    Command(Vec<String>),
}

#[derive(Debug, Clone, Default, Deserialize)]
#[serde(deny_unknown_fields, default)]
pub struct CheckConfig {
    /// A list, because a corpus may own more than one format.
    pub external: Vec<External>,
}

#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct External {
    /// The command and its arguments. Run with the corpus root as the
    /// working directory, so a tool that defaults to `.` needs no argument
    /// and `run` stays exactly what the corpus wrote.
    pub run: Vec<String>,
    /// Off without deleting the entry — the same knob `[rules.…]` gives a
    /// built-in rule, for the same reason.
    pub enabled: Option<bool>,
    /// Applied to every finding this check returns, replacing whatever the
    /// tool chose. The corpus has decided how much this check matters and
    /// the tool no longer gets a vote.
    pub severity: Option<Severity>,
}

impl External {
    pub fn is_enabled(&self) -> bool {
        self.enabled.unwrap_or(true)
    }

    /// What this entry is called in a listing: the program, not the whole
    /// command line.
    pub fn name(&self) -> &str {
        self.run.first().map(String::as_str).unwrap_or("")
    }

    pub fn command_line(&self) -> String {
        self.run.join(" ")
    }
}

impl Config {
    /// Read `tw.toml`, or the built-in default if there is none.
    ///
    /// A malformed file is an error and a missing one is not, for the
    /// reason `markdoc-lint` gives about its own: falling back to the
    /// defaults would turn a typo into "the check stopped running", which
    /// is the failure hardest to notice.
    pub fn load(dir: &Path) -> Result<Self, String> {
        let path = dir.join(CONFIG_FILENAME);
        match std::fs::read_to_string(&path) {
            Ok(text) => Self::parse(&text).map_err(|e| format!("{}: {e}", path.display())),
            Err(e) if e.kind() == std::io::ErrorKind::NotFound => Ok(Self::default()),
            Err(e) => Err(format!("{}: {e}", path.display())),
        }
    }

    pub fn parse(text: &str) -> Result<Self, String> {
        let config: Self = toml::from_str(text).map_err(|e| e.to_string())?;
        for entry in &config.check.external {
            if entry.run.is_empty() {
                return Err("[[check.external]] run = [] names no command".to_string());
            }
        }
        // Each of these becomes part of a path, so each is one name.
        let plain =
            |s: &str| !s.is_empty() && s != "." && s != ".." && !s.contains(['/', '\\', ':']);
        for (name, tool) in &config.tools {
            if !plain(name) {
                return Err(format!("[tools.{name}]: `{name}` is not a program's name"));
            }
            if tools::builtin(name).is_some() {
                return Err(format!(
                    "[tools.{name}]: tw pins {name} itself, from the `{name}` \
                     entry of tooling-versions.json; this would never be used"
                ));
            }
            if !plain(&tool.pin) {
                return Err(format!(
                    "[tools.{name}] pin = `{}` is not a pin's name",
                    tool.pin
                ));
            }
            if let Some(asset) = &tool.asset
                && !plain(&asset.replace(['{', '}'], ""))
            {
                return Err(format!(
                    "[tools.{name}] asset = `{asset}` is not a file name"
                ));
            }
            if let Some(checkout) = &tool.checkout
                && !plain(checkout)
            {
                return Err(format!(
                    "[tools.{name}] checkout = `{checkout}` is not a directory's name"
                ));
            }
        }
        Ok(config)
    }

    /// The program `name` as a pinned tool: `tw`'s own, or one `[tools]`
    /// declares. `None` for anything else, which is looked for on `PATH`.
    pub fn launched(&self, name: &str) -> Option<tools::Launched> {
        tools::builtin(name).or_else(|| {
            self.tools
                .get(name)
                .map(|tool| tools::Launched::configured(name, tool))
        })
    }

    /// Every pinned tool this corpus runs: `tw`'s own and its `[tools]`.
    pub fn all_launched(&self) -> Vec<tools::Launched> {
        [tools::MARKDOC_LS, tools::MARKDOC_PDF]
            .into_iter()
            .chain(
                self.tools
                    .iter()
                    .map(|(name, tool)| tools::Launched::configured(name, tool)),
            )
            .collect()
    }

    /// The entries that will actually run.
    pub fn active(&self) -> impl Iterator<Item = &External> {
        self.check.external.iter().filter(|e| e.is_enabled())
    }
}

/// Run one external check and return what it found.
///
/// Every failure here is fatal rather than skipped. A check that quietly
/// did not run reports a clean corpus, which is indistinguishable from a
/// corpus that is clean — the exact failure `--list-rules` exists to make
/// visible, and not one to reintroduce through the back door.
pub fn run(entry: &External, root: &Path, config: &Config) -> Result<Vec<Diagnostic>, String> {
    let program = resolve(entry.name(), root, config)
        .map_err(|e| format!("{e}\n  (named by [[check.external]] in tw.toml)"))?;

    // On Windows `program` may be a `.cmd` or `.bat` (`resolve` goes through
    // PATHEXT). Rust's std runs those through cmd.exe and escapes each
    // argument for it, and refuses to start one with an argument it cannot
    // escape safely, so `run` reaches the script as written.
    let mut command = Command::new(&program);
    crate::dotenv::apply(&mut command);
    let output = command
        .args(&entry.run[1..])
        // The corpus root, so `run` carries no path and the tool's own
        // default (`.`) is the right one.
        .current_dir(root)
        .output()
        .map_err(|e| format!("{}: {e}", program.display()))?;

    // The tool's own progress and errors belong to the user, not to us.
    if !output.stderr.is_empty() {
        eprint!("{}", String::from_utf8_lossy(&output.stderr));
    }

    // 0 clean and 1 findings are both answers. Anything else -- 2 for
    // misuse, or a signal -- means the question was not answered, and a
    // question not answered is not a corpus with nothing wrong with it.
    match output.status.code() {
        Some(0 | 1) => {}
        Some(code) => {
            return Err(format!(
                "{} exited {code}. Its findings were not read.",
                entry.command_line()
            ));
        }
        None => {
            return Err(format!(
                "{} was killed before it finished.",
                entry.command_line()
            ));
        }
    }

    let stdout = String::from_utf8_lossy(&output.stdout);
    // Said before the parser gets a chance to describe it as a syntax
    // error. Nothing at all is the commonest way for this to go wrong -- a
    // tool run without its --json flag, or one that does not have one --
    // and "EOF while parsing a value" is not what happened.
    if stdout.trim().is_empty() {
        return Err(format!(
            "{} printed nothing. A tool named by [[check.external]] prints, \
             under --json, an object with a \"diagnostics\" array of \
             markdoc-lint diagnostics -- including when it found none.",
            entry.command_line()
        ));
    }
    let report: Report = serde_json::from_str(&stdout).map_err(|e| {
        format!(
            "{} did not print a report: {e}\n\
             A tool named by [[check.external]] prints, under --json, an \
             object with a \"diagnostics\" array of markdoc-lint diagnostics.",
            entry.command_line()
        )
    })?;

    let mut diagnostics = report.diagnostics;
    if let Some(severity) = entry.severity {
        for d in &mut diagnostics {
            d.severity = severity;
        }
    }
    Ok(diagnostics)
}

/// What a tool named by `[[check.external]]` prints.
///
/// Only `diagnostics` is read. The counts every such tool also prints are
/// its own summary of what it found, and recounting them here would be a
/// second place for the total to be wrong.
#[derive(Deserialize)]
struct Report {
    #[serde(default)]
    diagnostics: Vec<Diagnostic>,
}

/// A pinned tool first -- `tw`'s own or one `[tools]` declares -- then `PATH`.
///
/// The pinned ones are resolved the way every other launched tool is, so an
/// external check runs the same bytes CI does -- which is the whole reason
/// `tooling-versions.json` exists. A name nothing pins still works, so a
/// corpus can name a tool of its own.
///
/// On `PATH` the name is looked up as a command line has it -- through
/// `PATHEXT` on Windows, not forced to `.exe` -- because the commonest
/// program named here, npm, is `npm.cmd` there.
pub fn resolve(name: &str, root: &Path, config: &Config) -> Result<PathBuf, String> {
    resolve_in(name, root, config, &tools::Search::from_env())
}

/// `resolve`, searching `search` rather than this process's `PATH`, so a
/// test can search as Windows does on any platform.
fn resolve_in(
    name: &str,
    root: &Path,
    config: &Config,
    search: &tools::Search,
) -> Result<PathBuf, String> {
    if let Some(launched) = config.launched(name) {
        return launched.resolve(root);
    }
    search.find(name).ok_or_else(|| {
        format!(
            "{name} is not pinned -- neither by tw nor under [tools] in tw.toml -- \
             and is not on PATH."
        )
    })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn no_config_means_no_external_checks() {
        let c = Config::default();
        assert_eq!(c.active().count(), 0);
    }

    #[test]
    fn an_entry_is_a_command_and_two_optional_knobs() {
        let c = Config::parse(
            r#"
            [[check.external]]
            run = ["site-gen", "--check", "--json"]
            "#,
        )
        .unwrap();
        let entry = c.active().next().unwrap();
        assert_eq!(entry.name(), "site-gen");
        assert_eq!(entry.command_line(), "site-gen --check --json");
        assert!(entry.severity.is_none());
    }

    #[test]
    fn an_entry_can_be_switched_off_and_re_levelled() {
        let c = Config::parse(
            r#"
            [[check.external]]
            run = ["a"]
            enabled = false

            [[check.external]]
            run = ["b"]
            severity = "warning"
            "#,
        )
        .unwrap();
        assert_eq!(c.check.external.len(), 2);
        let active: Vec<_> = c.active().collect();
        assert_eq!(active.len(), 1);
        assert_eq!(active[0].name(), "b");
        assert_eq!(active[0].severity, Some(Severity::Warning));
    }

    #[test]
    fn a_misspelled_key_is_an_error_rather_than_a_silent_no_op() {
        // The same reason markdoc-lint.toml denies unknown fields: a typo
        // that parses is a check that stops running with nobody noticing.
        let err = Config::parse("[[check.external]]\nrun = [\"a\"]\nseverty = \"warning\"\n")
            .unwrap_err();
        assert!(err.contains("severty"), "{err}");
    }

    #[test]
    fn a_command_with_no_command_in_it_is_refused() {
        let err = Config::parse("[[check.external]]\nrun = []\n").unwrap_err();
        assert!(err.contains("names no command"), "{err}");
    }

    #[test]
    fn a_corpus_names_its_own_pinned_programs_and_what_preview_runs() {
        let c = Config::parse(
            r#"
            [tools.site-gen]
            pin = "site-toolkit"
            checkout = "site-toolkit-src"

            [preview]
            run = "site-gen"
            "#,
        )
        .unwrap();
        assert_eq!(
            c.preview.run,
            Some(PreviewRun::Program("site-gen".to_string()))
        );
        let line =
            Config::parse("[preview]\nrun = [\"npm\", \"run\", \"preview\", \"--\"]\n").unwrap();
        assert_eq!(
            line.preview.run,
            Some(PreviewRun::Command(
                ["npm", "run", "preview", "--"].map(String::from).to_vec()
            ))
        );
        let tool = c.launched("site-gen").unwrap();
        assert_eq!(tool.source.pinned_by, "site-toolkit");
        assert_eq!(tool.env_override, "SITE_GEN_BIN");
        assert_eq!(tool.built_in.as_deref(), Some("site-toolkit-src"));
        // tw's own are there whatever the file says, and nothing else is.
        assert!(c.launched("markdoc-ls").is_some());
        assert!(c.launched("something-on-path").is_none());
        let names: Vec<_> = c
            .all_launched()
            .into_iter()
            .map(|l| l.stem.to_string())
            .collect();
        assert_eq!(names, ["markdoc-ls", "markdoc-pdf", "site-gen"]);
    }

    #[test]
    fn a_pinned_program_s_names_are_names_and_not_paths() {
        for (toml, says) in [
            (
                "[tools.markdoc-ls]\npin = \"x\"",
                "tw pins markdoc-ls itself",
            ),
            ("[tools.\"../x\"]\npin = \"x\"", "not a program's name"),
            ("[tools.x]\npin = \"a/b\"", "not a pin's name"),
            (
                "[tools.x]\npin = \"x\"\nasset = \"../x-{platform}\"",
                "not a file name",
            ),
            (
                "[tools.x]\npin = \"x\"\ncheckout = \"..\"",
                "not a directory's name",
            ),
            ("[tools.x]\npin = \"x\"\npinn = \"y\"", "pinn"),
            ("[tools.x]\n", "pin"),
            ("[preview]\nrun = \"x\"\nargs = []", "args"),
        ] {
            let err = Config::parse(toml).unwrap_err();
            assert!(err.contains(says), "{toml}: {err}");
        }
    }

    /// A directory of this test's own holding what Node's installer puts in
    /// its directory on Windows: `npm` (a sh script), `npm.cmd`, `npm.ps1`.
    fn node_dir(test: &str) -> PathBuf {
        let dir = std::env::temp_dir().join(format!("tw-resolve-{test}-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        for file in ["npm", "npm.cmd", "npm.ps1"] {
            std::fs::write(dir.join(file), "").unwrap();
        }
        dir
    }

    /// `resolve`'s PATH step finds a program as a command line does, which
    /// on Windows is through PATHEXT: `run = ["npm", ...]` is `npm.cmd`.
    /// Searched with Windows' PATHEXT on every platform, in a directory this
    /// process's PATH does not have -- so a lookup that searches PATH
    /// itself, or forces `.exe` again (`tools::which(&tools::exe(name))`,
    /// the bug this replaced), fails here.
    #[test]
    fn a_program_on_path_is_found_as_a_command_line_finds_it() {
        let dir = node_dir("pathext");
        let root = Path::new("/nonexistent");
        let config = Config::default();
        let windows = tools::Search {
            dirs: vec![dir.clone()],
            pathext: [".COM", ".EXE", ".BAT", ".CMD"].map(String::from).to_vec(),
        };
        assert_eq!(
            resolve_in("npm", root, &config, &windows),
            Ok(dir.join("npm.cmd"))
        );
        // Named with an extension PATHEXT lists, it is taken as it is.
        assert_eq!(
            resolve_in("npm.cmd", root, &config, &windows),
            Ok(dir.join("npm.cmd"))
        );
        // Off Windows there is no PATHEXT, and the name is the file's.
        let elsewhere = tools::Search {
            dirs: vec![dir.clone()],
            pathext: Vec::new(),
        };
        assert_eq!(
            resolve_in("npm", root, &config, &elsewhere),
            Ok(dir.join("npm"))
        );
        // Not there is said, with the name looked for.
        let err = resolve_in("npx", root, &config, &windows).unwrap_err();
        assert!(err.starts_with("npx is not pinned"), "{err}");
        let _ = std::fs::remove_dir_all(&dir);
    }

    /// The same through `resolve` itself, with this process's PATH and the
    /// PATHEXT Windows sets: the directory goes in front of PATH.
    #[cfg(windows)]
    #[test]
    fn on_windows_resolve_finds_npm_cmd_on_path() {
        let dir = node_dir("windows");
        let _path = crate::PATH_LOCK
            .lock()
            .unwrap_or_else(|poisoned| poisoned.into_inner());
        let saved = std::env::var_os("PATH");
        let in_front = std::env::join_paths(
            std::iter::once(dir.clone()).chain(saved.iter().flat_map(std::env::split_paths)),
        )
        .unwrap();
        // SAFETY: under PATH_LOCK, which every test that reads PATH holds,
        // and restored below before any assertion.
        unsafe { std::env::set_var("PATH", &in_front) };
        let found = resolve("npm", Path::new("/nonexistent"), &Config::default());
        unsafe {
            match saved {
                Some(v) => std::env::set_var("PATH", v),
                None => std::env::remove_var("PATH"),
            }
        }
        assert_eq!(found, Ok(dir.join("npm.cmd")));
        let _ = std::fs::remove_dir_all(&dir);
    }
}