jsonvet-cli 3.2.0

The jsonvet command: checks JSON, I-JSON, JSONC, JWCC (HuJSON), JSON5 and JSON Lines files, with JSON Schema checks and SARIF output.
Documentation
//! The command line.

use std::ffi::OsString;
use std::path::PathBuf;

use lexopt::prelude::*;

use crate::output::Format;
use crate::settings::{DialectPattern, Settings, parse_rule, parse_severity};

pub(crate) const HELP: &str = "\
Check JSON, I-JSON, JSONC, JWCC (HuJSON), JSON5 and JSON Lines files for syntax errors,
duplicate keys and the rules of each dialect.

Usage: jsonvet [OPTIONS] [FILE]...

A FILE of - reads standard input. A directory stands for the files under it with an extension
or name jsonvet checks by default. jsonvet skips hidden files there, and the files that
.gitignore, .ignore and the exclude setting name. A file named on the command line is always
checked.

Options:
      --dialect DIALECT[:GLOB]  Check files matching GLOB (every file, without one) as DIALECT:
                                json, i-json, jsonc, jwcc, json5, jsonl, or auto for the file
                                extension's default. Also accepted: ijson, hujson (jwcc),
                                ndjson and json-lines (jsonl). Repeatable; the last match wins.
                                Files with any other extension are checked as json5;
                                extensions match in lower case only.
      --strict GLOB             Same as --dialect json:GLOB; --strict '!GLOB' means auto:GLOB.
      --error RULE              Report RULE as an error. Repeatable, as are the next two.
      --warn RULE               Report RULE as a warning.
      --ignore RULE             Do not check RULE.
      --max-warnings N          Fail when there are more than N warnings.
      --format FORMAT           Print problems as text (the default), sarif (one SARIF 2.1.0
                                document, for GitHub code scanning) or json (one JSON document;
                                docs/usage.md in the repository lists its fields).
      --color WHEN              Color text output: auto (the default), always or never. Auto
                                colors it on a terminal, unless NO_COLOR is set; FORCE_COLOR
                                colors it anywhere, and FORCE_COLOR=0 or false nowhere. On a
                                terminal, each problem also shows the line of the file it is
                                on; elsewhere it stays one line.
      --schema FILE             Check each file against the JSON Schema in FILE, reported
                                under the rule schema, instead of the schemas from settings
                                or a file's own local $schema. Nothing is fetched. Limits:
                                docs/usage.md in the repository.
      --stdin-filename PATH     Name standard input PATH in the output, and pick its dialect
                                and settings by PATH. With no FILE, check standard input.
      --config FILE             Read settings from FILE instead of searching for one.
      --no-config               Do not read a settings file.
      --list-rules              List the rules, with their default severities, and exit.
      --explain RULE            Explain RULE, with an example, and exit.
  -h, --help                    Print this help.
  -V, --version                 Print the version.

Rules: syntax, duplicate-key, invalid-number, invalid-code-point, byte-order-mark,
missing-final-newline (--list-rules says more). With a schema (--schema, the schemas setting
or a local $schema in the file), errors also come under the rule schema; they are always errors,
and --error, --warn, --ignore and settings files do not take schema.

Settings come from jsonvet.toml, or [tool.jsonvet] in pyproject.toml: for each file, the nearest
one in its folder or a parent, up to the repository root (without .git, the working directory).
With none, jsonvet/jsonvet.toml in $XDG_CONFIG_HOME or ~/.config (%APPDATA% on Windows) applies.
Options on the command line win.

Exit status: 0 when no file has an error, 1 when one does, 2 for a usage error, such as a
schema that cannot be read or used.";

/// Where settings come from besides the command line.
#[derive(Debug, PartialEq, Eq)]
pub(crate) enum ConfigSource {
    Search,
    File(PathBuf),
    None,
}

#[derive(Debug)]
pub(crate) struct Args {
    pub(crate) files: Vec<OsString>,
    pub(crate) settings: Settings,
    pub(crate) max_warnings: Option<usize>,
    pub(crate) config: ConfigSource,
    pub(crate) format: Format,
    /// Whether to color text output, from `--color`: `None` for `auto`.
    pub(crate) color: Option<bool>,
    pub(crate) schema: Option<PathBuf>,
    /// The name standard input goes by, from `--stdin-filename`.
    pub(crate) stdin_filename: Option<OsString>,
}

#[derive(Debug)]
pub(crate) enum Command {
    Check(Args),
    Help,
    Version,
    ListRules,
    /// `--explain`'s text for the rule.
    Explain(String),
}

fn parse_format(name: &str) -> Result<Format, String> {
    match name {
        "text" => Ok(Format::Text),
        "sarif" => Ok(Format::Sarif),
        "json" => Ok(Format::Json),
        _ => {
            let hint = jsonvet::did_you_mean(name, ["text", "sarif", "json"]);
            Err(format!(
                "--format takes text, sarif or json, not `{name}`{hint}"
            ))
        }
    }
}

fn parse_color(when: &str) -> Result<Option<bool>, String> {
    match when {
        "auto" => Ok(None),
        "always" => Ok(Some(true)),
        "never" => Ok(Some(false)),
        _ => {
            let hint = jsonvet::did_you_mean(when, ["auto", "always", "never"]);
            Err(format!(
                "--color takes auto, always or never, not `{when}`{hint}"
            ))
        }
    }
}

pub(crate) fn parse(args: impl IntoIterator<Item = OsString>) -> Result<Command, String> {
    let mut parser = lexopt::Parser::from_args(args);
    // Otherwise `-x=a.json` would come back as `-x` and `a.json`, losing the `=`.
    parser.set_short_equals(false);
    let mut files = Vec::new();
    let mut settings = Settings::default();
    let mut max_warnings = None;
    let mut config = ConfigSource::Search;
    let mut format = Format::Text;
    let mut color = None;
    let mut schema = None;
    let mut stdin_filename = None;
    loop {
        // lexopt reads a non-UTF-8 argument that starts with `-` lossily. No option has such a
        // name, so it is a file, kept as given. An existing file named like `--dialect=json`
        // is a file too, as pre-commit puts file names after the options with no `--`.
        if let Some(file) = parser.try_raw_args().and_then(|mut raw| {
            raw.next_if(|arg| match arg.to_str() {
                None => true,
                Some(arg) => arg.starts_with("--") && arg.contains('=') && exists(arg),
            })
        }) {
            files.push(file);
            continue;
        }
        let Some(arg) = parser.next().map_err(|e| e.to_string())? else {
            break;
        };
        match arg {
            Long("dialect") => settings
                .dialects
                .push(DialectPattern::parse(&value(&mut parser)?)?),
            Long("strict") => {
                let glob = value(&mut parser)?;
                settings.dialects.push(match glob.strip_prefix('!') {
                    Some(glob) => DialectPattern::parse(&format!("auto:{glob}"))?,
                    None => DialectPattern::parse(&format!("json:{glob}"))?,
                });
            }
            Long(severity @ ("error" | "warn" | "ignore")) => {
                let severity = parse_severity(severity)?;
                let rule = parse_rule(&value(&mut parser)?)?;
                settings.rules.push((rule, severity));
            }
            Long("max-warnings") => {
                let n = value(&mut parser)?;
                max_warnings = Some(
                    n.parse()
                        .map_err(|_| format!("--max-warnings takes a number, not `{n}`"))?,
                );
            }
            Long("format") => format = parse_format(&value(&mut parser)?)?,
            Long("color") => color = parse_color(&value(&mut parser)?)?,
            Long("config") => config = ConfigSource::File(PathBuf::from(value(&mut parser)?)),
            Long("no-config") => config = ConfigSource::None,
            Long("list-rules") => return Ok(Command::ListRules),
            Long("explain") => {
                return crate::rules::explain(&value(&mut parser)?).map(Command::Explain);
            }
            Long("schema") => schema = Some(PathBuf::from(value(&mut parser)?)),
            Long("stdin-filename") => {
                stdin_filename = Some(parser.value().map_err(|e| e.to_string())?);
            }
            // pre-commit puts file names after the options with no `--`, so an existing file
            // named like `-x.json`, `-h.json` or `--y.json` is a file, not an option.
            arg => {
                let (mut file, separator) = match arg {
                    Short(c) => (OsString::from(format!("-{c}")), ""),
                    Long(name) => (OsString::from(format!("--{name}")), "="),
                    Value(file) => {
                        files.push(file);
                        continue;
                    }
                };
                let rest = rest(&mut parser);
                if rest.is_empty() {
                    match file.to_str() {
                        Some("-h" | "--help") => return Ok(Command::Help),
                        Some("-V" | "--version") => return Ok(Command::Version),
                        _ => {}
                    }
                } else {
                    file.push(separator);
                    file.push(rest);
                }
                files.push(on_disk(file)?);
            }
        }
    }
    if files.iter().filter(|file| *file == STDIN).count() > 1 {
        return Err("`-` (standard input) can be given only once".to_owned());
    }
    if files.is_empty() && stdin_filename.is_some() {
        files.push(STDIN.into());
    }
    Ok(Command::Check(Args {
        files,
        settings,
        max_warnings,
        config,
        format,
        color,
        schema,
        stdin_filename,
    }))
}

/// The file name that stands for standard input.
pub(crate) const STDIN: &str = "-";

fn exists(path: impl AsRef<std::path::Path>) -> bool {
    std::fs::symlink_metadata(path).is_ok()
}

/// An argument jsonvet has no option for: a file if one has that name, or else a mistyped
/// option, such as `--strcit` or `-q`.
fn on_disk(file: OsString) -> Result<OsString, String> {
    if exists(&file) {
        Ok(file)
    } else {
        Err(format!("unknown option `{}`", file.to_string_lossy()))
    }
}

fn value(parser: &mut lexopt::Parser) -> Result<String, String> {
    parser
        .value()
        .map_err(|e| e.to_string())?
        .into_string()
        .map_err(|v| format!("not valid UTF-8: {}", v.to_string_lossy()))
}

/// The rest of the current argument after an unknown option: the remaining letters of
/// `-dash.json`, or the value of `--name=value`.
fn rest(parser: &mut lexopt::Parser) -> OsString {
    parser.optional_value().unwrap_or_default()
}

#[cfg(test)]
mod tests {
    use std::collections::BTreeSet;

    use super::{Command, ConfigSource, Format, HELP, parse};
    use jsonvet::{Dialect, Rule, Severity};

    #[test]
    fn help_names_every_rule_and_dialect() {
        let words: Vec<&str> = HELP
            .split(|c: char| !(c.is_ascii_alphanumeric() || c == '-'))
            .collect();
        let missing: Vec<String> = Rule::ALL
            .iter()
            .map(|rule| rule.id().to_owned())
            .chain(Dialect::ALL.iter().map(ToString::to_string))
            .filter(|name| !words.contains(&name.as_str()))
            .collect();
        assert!(missing.is_empty(), "not in the help: {missing:?}");
        let wide: Vec<&str> = HELP.lines().filter(|l| l.chars().count() > 96).collect();
        assert!(wide.is_empty(), "help lines over 96 columns: {wide:?}");
    }

    /// usage.md's option list names the options `--help` does, and the parser knows each one.
    /// Their wording differs, so only the names are compared. `--help` and `--version` need no
    /// line in usage.md.
    #[test]
    fn usage_md_lists_the_options_help_does() {
        let usage = include_str!("../../../docs/usage.md").replace("\r\n", "\n");
        let block = |text: &str, start: &str, end: &str| {
            let (_, rest) = text.split_once(start).expect(start);
            rest.split_once(end).expect(end).0.to_owned()
        };
        let options = |text: &str| -> BTreeSet<String> {
            text.split(|c: char| !(c.is_ascii_alphanumeric() || c == '-'))
                .filter(|word| word.len() > 2 && word.starts_with("--"))
                .map(ToOwned::to_owned)
                .collect()
        };
        let mut help = options(&block(HELP, "\nOptions:\n", "\n\nRules:"));
        for option in &help {
            let error = parse([option.as_str()].iter().map(Into::into)).err();
            assert_ne!(error, Some(format!("unknown option `{option}`")));
        }
        help.retain(|option| option != "--help" && option != "--version");
        let docs = options(&block(&usage, "## Options\n\n```text\n", "```"));
        assert_eq!(help, docs, "options in --help and in docs/usage.md");
    }

    fn check(args: &[&str]) -> super::Args {
        match parse(args.iter().map(Into::into)) {
            Ok(Command::Check(args)) => args,
            other => panic!("expected a check, got {other:?}"),
        }
    }

    #[test]
    fn files_that_look_like_options_stay_files() {
        let args = check(&["--", "-dash.json", "--y.json", "--dialect=json", "a.json"]);
        assert_eq!(
            args.files,
            ["-dash.json", "--y.json", "--dialect=json", "a.json"]
        );
        // An unknown `-x` or `--name`, or a known `--name=value`, is a file only when it exists;
        // tests/cli.rs covers that case.
        for unknown in [
            "--strcit",
            "--help=x",
            "--x.json",
            "-q",
            "-dash.json",
            "-h.json",
            "-x=a.json",
        ] {
            assert_eq!(
                parse(["a.json", unknown].iter().map(Into::into)).err(),
                Some(format!("unknown option `{unknown}`"))
            );
        }
        assert!(matches!(
            parse(["a.json", "-h"].iter().map(Into::into)),
            Ok(Command::Help)
        ));
        assert!(matches!(
            parse(["--version"].iter().map(Into::into)),
            Ok(Command::Version)
        ));
    }

    #[test]
    fn rule_limit_and_config_flags_parse_and_bad_values_fail() {
        let args = check(&[
            "--warn=duplicate-key",
            "--max-warnings",
            "3",
            "--no-config",
            "--format=sarif",
            "x.jsonc",
        ]);
        assert_eq!(
            args.settings.rules,
            [(Rule::DuplicateKey, Severity::Warning)]
        );
        assert_eq!(args.max_warnings, Some(3));
        assert_eq!(args.config, ConfigSource::None);
        assert_eq!(args.format, Format::Sarif);
        assert_eq!(check(&["x.json"]).format, Format::Text);
        assert_eq!(check(&["--format=text", "x.json"]).format, Format::Text);
        assert_eq!(check(&["--format", "json", "x.json"]).format, Format::Json);
        assert!(parse(["--format", "jsonl"].iter().map(Into::into)).is_err());
        // Value names are case-sensitive, as in clap and ruff, but a wrong case gets a hint.
        assert_eq!(
            parse(["--format", "SARIF"].iter().map(Into::into)).err(),
            Some(
                "--format takes text, sarif or json, not `SARIF` (did you mean `sarif`?)"
                    .to_owned()
            )
        );
        assert!(parse(["--error", "nope"].iter().map(Into::into)).is_err());
        assert!(parse(["--dialect", "yaml"].iter().map(Into::into)).is_err());
        assert!(parse(["--strict"].iter().map(Into::into)).is_err());
    }
}