#![cfg(feature = "cli")]
mod document_schema;
use std::ffi::OsString;
use std::io::Write;
use std::path::Path;
use assert_cmd::Command;
use predicates::prelude::*;
use tempfile::NamedTempFile;
const PROSE: &str = "The committee approved the proposal. Three amendments were submitted \
by the working group. The chair adjourned the meeting.";
#[cfg(feature = "model2vec")]
const DOCUMENT_COMMANDS: &[&str] = &["analyze", "summarize", "keyphrases", "clusters"];
#[cfg(not(feature = "model2vec"))]
const DOCUMENT_COMMANDS: &[&str] = &["analyze", "summarize", "keyphrases"];
fn run(args: &[&str]) -> (u8, String, String) {
let argv = std::iter::once(OsString::from("matra")).chain(args.iter().map(OsString::from));
let mut out: Vec<u8> = Vec::new();
let mut err: Vec<u8> = Vec::new();
let code = matra::cli::run(argv, &mut out, &mut err);
(
code,
String::from_utf8(out).expect("stdout is utf8"),
String::from_utf8(err).expect("stderr is utf8"),
)
}
fn fixture(contents: &str, suffix: &str) -> NamedTempFile {
let mut f = tempfile::Builder::new()
.suffix(suffix)
.tempfile()
.expect("temp file");
f.write_all(contents.as_bytes()).expect("write fixture");
f.flush().expect("flush fixture");
f
}
fn path_of(f: &NamedTempFile) -> &str {
f.path().to_str().expect("utf8 path")
}
fn scoped(home: &Path) -> Command {
let mut cmd = Command::cargo_bin("matra").expect("binary built with --features cli");
cmd.env_clear()
.env("HOME", home)
.env("XDG_CONFIG_HOME", home.join("config"))
.env("XDG_DATA_HOME", home.join("data"))
.env("PATH", std::env::var("PATH").unwrap_or_default());
cmd
}
#[test]
fn help_lists_every_command() {
let (code, out, _) = run(&["--help"]);
assert_eq!(code, 0);
for command in [
"analyze",
"summarize",
"keyphrases",
"clusters",
"config",
"completions",
] {
assert!(out.contains(command), "missing `{command}` in:\n{out}");
}
}
#[test]
fn help_lists_the_agent_flags() {
let (code, out, _) = run(&["--help"]);
assert_eq!(code, 0);
assert!(out.contains("--skill"), "{out}");
assert!(out.contains("--reference"), "{out}");
assert!(out.contains("--schema"), "{out}");
}
#[test]
fn help_names_the_program_whatever_argv_zero_says() {
let argv = ["/opt/weird/path/to/matra-0.1.0", "--help"]
.into_iter()
.map(OsString::from);
let mut out: Vec<u8> = Vec::new();
let mut err: Vec<u8> = Vec::new();
matra::cli::run(argv, &mut out, &mut err);
let out = String::from_utf8(out).expect("utf8");
assert!(out.contains("Usage: matra"), "{out}");
assert!(!out.contains("matra-0.1.0"), "{out}");
}
#[test]
fn version_names_the_version_then_the_compiled_features() {
let (code, out, _) = run(&["--version"]);
assert_eq!(code, 0);
let mut lines = out.lines();
assert_eq!(
lines.next(),
Some(format!("matra {}", env!("CARGO_PKG_VERSION")).as_str())
);
let features = lines.next().expect("a features line");
assert!(features.starts_with("features:"), "{features}");
assert!(features.contains("udpipe"), "{features}");
assert!(features.contains("cli"), "{features}");
}
#[test]
fn unknown_command_is_rejected_on_stderr() {
let (code, out, err) = run(&["frobnicate"]);
assert_eq!(code, 2);
assert!(out.is_empty(), "usage errors do not go to stdout: {out}");
assert!(!err.is_empty());
}
#[test]
fn missing_path_argument_is_rejected() {
let (code, _, err) = run(&["analyze"]);
assert_eq!(code, 2);
assert!(!err.is_empty());
}
#[test]
fn missing_input_file_exits_two_without_loading_the_model() {
let missing = "/nonexistent/path/to/file.md";
for command in DOCUMENT_COMMANDS {
let (code, out, err) = run(&[command, missing]);
assert_eq!(code, 2, "{command}");
assert!(out.is_empty(), "{command} printed: {out}");
assert!(err.contains("cannot read"), "{command}: {err}");
assert!(err.contains(missing), "{command} names the path: {err}");
}
}
#[test]
fn a_directory_is_refused_by_every_command_that_reads_one_document() {
let dir = tempfile::tempdir().expect("temp dir");
std::fs::write(dir.path().join("a.txt"), PROSE).expect("write");
std::fs::write(dir.path().join("b.txt"), PROSE).expect("write");
let path = dir.path().to_str().expect("utf8 path");
for command in DOCUMENT_COMMANDS.iter().filter(|c| **c != "analyze") {
let (code, out, err) = run(&[command, path]);
assert_eq!(code, 2, "{command}: {err}");
assert!(out.is_empty(), "{command} printed: {out}");
assert!(err.contains(path), "{command} names the path: {err}");
assert!(err.contains("is a directory"), "{command}: {err}");
assert!(err.contains("matra analyze"), "{command}: {err}");
}
}
#[test]
fn format_with_a_directory_is_refused() {
let dir = tempfile::tempdir().expect("temp dir");
let path = dir.path().to_str().expect("utf8 path");
let (code, out, err) = run(&["analyze", path, "--format", "markdown"]);
assert_eq!(code, 2, "{err}");
assert!(out.is_empty(), "{out}");
assert!(err.contains("--format"), "{err}");
}
#[test]
fn depth_needs_json() {
let (code, out, err) = run(&["analyze", "notes.md", "--depth", "sentence"]);
assert_eq!(code, 2);
assert!(out.is_empty(), "{out}");
assert!(err.contains("--json"), "{err}");
}
#[test]
fn format_takes_the_shared_vocabulary() {
let (code, _, err) = run(&["analyze", "x", "--format", "plain-text"]);
assert_eq!(code, 2, "the kebab spelling is not the vocabulary");
assert!(
err.contains("plain_text"),
"the refusal names the word: {err}"
);
for format in ["markdown", "plain_text", "blocks"] {
let (code, _, err) = run(&["analyze", "/nonexistent/x", "--format", format]);
assert_eq!(code, 2, "{format}");
assert!(
err.contains("cannot read"),
"{format} parsed, then the path failed: {err}"
);
}
}
fn failure_envelope(out: &str) -> serde_json::Value {
let parsed: serde_json::Value = serde_json::from_str(out).expect("stdout is one JSON object");
let mut keys: Vec<&str> = parsed
.as_object()
.expect("an object")
.keys()
.map(String::as_str)
.collect();
keys.sort_unstable();
assert_eq!(
keys,
["command", "error", "format_version", "input", "result"]
);
assert_eq!(parsed["format_version"], 2);
assert!(parsed["result"].is_null(), "a failure has no result");
document_schema::assert_valid("error", &parsed["error"], "the failure envelope");
parsed
}
#[test]
fn a_failure_under_json_is_an_envelope_on_stdout() {
let missing = "/nonexistent/path/to/file.md";
let (code, out, err) = run(&["analyze", missing, "--json"]);
assert_eq!(code, 2);
assert!(err.starts_with("matra: "), "{err}");
let envelope = failure_envelope(&out);
assert_eq!(envelope["command"], "analyze");
assert_eq!(envelope["input"], missing);
let error = &envelope["error"];
assert_eq!(error["kind"], "io");
assert_eq!(error["details"]["io_kind"], "not_found");
assert_eq!(error["details"]["path"], missing);
assert!(
err.contains(error["message"].as_str().expect("a message")),
"stderr carries the same message: {err}"
);
}
#[test]
fn the_command_line_s_own_refusals_are_invalid_input() {
let dir = tempfile::tempdir().expect("temp dir");
let path = dir.path().to_str().expect("utf8 path");
for (args, command, reason) in [
(
vec!["summarize", path, "--json"],
"summarize",
"directory_for_one_document",
),
(
vec!["analyze", path, "--format", "blocks", "--json"],
"analyze",
"format_with_directory",
),
(
vec!["-r", "json", "--json"],
"skill",
"reference_without_skill",
),
(
vec!["--skill", "-r", "jsn", "--json"],
"skill",
"reference_unknown",
),
(
vec!["--schema", "documnet", "--json"],
"schema",
"schema_unknown",
),
] {
let (code, out, err) = run(&args);
assert_eq!(code, 2, "{args:?}: {err}");
let envelope = failure_envelope(&out);
assert_eq!(envelope["command"], command, "{args:?}");
assert_eq!(envelope["error"]["kind"], "invalid_input", "{args:?}");
assert_eq!(envelope["error"]["details"]["reason"], reason, "{args:?}");
}
}
#[test]
fn a_usage_failure_under_json_is_an_envelope() {
let (code, out, err) = run(&["analyze", "--json"]);
assert_eq!(code, 2);
assert!(err.contains("Usage:"), "clap's own text on stderr: {err}");
let envelope = failure_envelope(&out);
assert_eq!(envelope["command"], "analyze");
assert_eq!(envelope["error"]["kind"], "invalid_input");
assert_eq!(envelope["error"]["details"]["reason"], "usage");
assert!(
envelope["error"]["message"]
.as_str()
.is_some_and(|m| m.contains("<PATH>")),
"{envelope}"
);
let (code, out, _) = run(&["--json", "--bogus"]);
assert_eq!(code, 2);
let envelope = failure_envelope(&out);
assert!(envelope["command"].is_null(), "{envelope}");
let (code, out, _) = run(&["--bogus"]);
assert_eq!(code, 2);
assert!(out.is_empty(), "{out}");
}
fn schema_dir() -> std::path::PathBuf {
Path::new(env!("CARGO_MANIFEST_DIR")).join("spec/schema/v2")
}
#[test]
fn every_schema_prints_its_file_verbatim() {
for name in [
"blocks",
"clusters",
"document",
"error",
"keyphrases",
"summary",
] {
let on_disk = std::fs::read_to_string(schema_dir().join(format!("{name}.schema.json")))
.expect("read the schema");
let (code, out, err) = run(&["--schema", name]);
assert_eq!(code, 0, "{name}: {err}");
assert_eq!(out, on_disk, "{name}");
}
}
#[test]
fn the_schema_list_and_the_schema_json() {
let (code, out, err) = run(&["--schema"]);
assert_eq!(code, 0, "{err}");
let names: Vec<&str> = out
.lines()
.map(|line| line.split_whitespace().next().expect("a name"))
.collect();
assert_eq!(
names,
[
"blocks",
"clusters",
"document",
"error",
"keyphrases",
"summary"
]
);
let (code, out, _) = run(&["--schema", "--json"]);
assert_eq!(code, 0);
let parsed: serde_json::Value = serde_json::from_str(&out).expect("JSON");
assert_eq!(parsed["command"], "schema");
assert!(parsed["error"].is_null());
assert_eq!(
parsed["result"]["schemas"].as_array().map(Vec::len),
Some(6)
);
let (code, out, _) = run(&["--schema", "document", "--json"]);
assert_eq!(code, 0);
let parsed: serde_json::Value = serde_json::from_str(&out).expect("JSON");
assert_eq!(parsed["result"]["name"], "document");
assert_eq!(
parsed["result"]["schema"]["title"],
"matra Document, schema 2.x"
);
}
#[test]
fn the_schema_outranks_a_subcommand_and_conflicts_with_the_skill() {
let (code, out, err) = run(&["analyze", "/nonexistent/x.md", "--schema", "error"]);
assert_eq!(code, 0, "{err}");
assert!(out.contains("matra error"), "{out}");
let (code, _, _) = run(&["--schema", "--skill"]);
assert_eq!(code, 2);
}
#[test]
fn completions_generate_for_every_supported_shell() {
for shell in ["bash", "zsh", "fish"] {
let (code, out, err) = run(&["completions", shell]);
assert_eq!(code, 0, "{shell}: {err}");
assert!(out.contains("matra"), "{shell} script names the command");
assert!(out.len() > 200, "{shell} script looks truncated");
}
}
#[test]
fn completions_into_a_pipe_closed_early_exit_0() {
use std::io::Read;
use std::process::{Command as Process, Stdio};
for shell in ["bash", "zsh", "fish"] {
let mut child = Process::new(env!("CARGO_BIN_EXE_matra"))
.args(["completions", shell])
.stdout(Stdio::piped())
.stderr(Stdio::piped())
.spawn()
.expect("the binary starts");
let mut first = [0u8; 1];
let mut stdout = child.stdout.take().expect("piped stdout");
stdout.read_exact(&mut first).expect("the script starts");
drop(stdout);
let output = child.wait_with_output().expect("the binary exits");
let stderr = String::from_utf8_lossy(&output.stderr);
assert_eq!(output.status.code(), Some(0), "{shell}: {stderr}");
assert!(!stderr.contains("panicked"), "{shell}: {stderr}");
}
}
#[test]
fn an_unknown_shell_is_rejected() {
let (code, _, _) = run(&["completions", "powershell"]);
assert_eq!(code, 2);
}
fn skill_dir() -> std::path::PathBuf {
Path::new(env!("CARGO_MANIFEST_DIR")).join("skills/matra")
}
fn reference_names() -> Vec<String> {
let dir = skill_dir().join("references");
let mut names: Vec<String> = std::fs::read_dir(&dir)
.unwrap_or_else(|e| panic!("read {}: {e}", dir.display()))
.map(|entry| entry.expect("dir entry").path())
.filter(|path| path.extension().is_some_and(|e| e == "md"))
.map(|path| {
path.file_stem()
.and_then(|s| s.to_str())
.expect("utf8 name")
.to_string()
})
.collect();
names.sort();
names
}
#[test]
fn the_skill_is_the_file_verbatim() {
let on_disk = std::fs::read_to_string(skill_dir().join("SKILL.md")).expect("read SKILL.md");
let (code, out, err) = run(&["--skill"]);
assert_eq!(code, 0, "{err}");
assert_eq!(out, on_disk);
}
#[test]
fn every_reference_prints_its_file_verbatim() {
for name in reference_names() {
let path = skill_dir().join("references").join(format!("{name}.md"));
let on_disk = std::fs::read_to_string(&path).expect("read the reference");
let (code, out, err) = run(&["--skill", "-r", &name]);
assert_eq!(code, 0, "{name}: {err}");
assert_eq!(out, on_disk, "{name} did not print its own file");
}
}
#[test]
fn the_reference_list_names_every_file_in_order() {
let (code, out, err) = run(&["--skill", "-r"]);
assert_eq!(code, 0, "{err}");
let listed: Vec<&str> = out
.lines()
.map(|line| line.split_whitespace().next().expect("a name"))
.collect();
assert_eq!(listed, reference_names());
for line in out.lines() {
let (_, summary) = line.split_once(" ").expect("a name then its summary");
assert!(!summary.trim().is_empty(), "no summary on: {line}");
}
}
#[test]
fn an_unknown_reference_exits_two_and_names_the_known_ones() {
let (code, out, err) = run(&["--skill", "-r", "jsn"]);
assert_eq!(code, 2);
assert!(out.is_empty(), "{out}");
for name in reference_names() {
assert!(err.contains(&name), "{err} omits `{name}`");
}
}
#[test]
fn a_reference_without_the_skill_flag_is_refused_by_name() {
for args in [vec!["-r"], vec!["-r", "json"], vec!["--reference", "json"]] {
let (code, out, err) = run(&args);
assert_eq!(code, 2, "{args:?}");
assert!(out.is_empty(), "{out}");
assert!(err.contains("--skill"), "{err}");
}
}
#[test]
fn the_skill_outranks_a_subcommand() {
let on_disk = std::fs::read_to_string(skill_dir().join("SKILL.md")).expect("read SKILL.md");
let (code, out, err) = run(&["analyze", "/nonexistent/path/to/file.md", "--skill"]);
assert_eq!(code, 0, "{err}");
assert_eq!(out, on_disk);
}
#[test]
fn the_skill_json_is_the_envelope() {
for (args, expect_list) in [
(vec!["--skill", "--json"], false),
(vec!["--skill", "-r", "--json"], true),
(vec!["--skill", "-r", "json", "--json"], false),
] {
let (code, out, err) = run(&args);
assert_eq!(code, 0, "{args:?}: {err}");
let parsed: serde_json::Value = serde_json::from_str(&out).expect("valid JSON");
let mut keys: Vec<&str> = parsed
.as_object()
.expect("an object")
.keys()
.map(String::as_str)
.collect();
keys.sort_unstable();
assert_eq!(
keys,
["command", "error", "format_version", "input", "result"]
);
assert_eq!(parsed["format_version"], 2);
assert_eq!(parsed["command"], "skill");
assert!(parsed["input"].is_null(), "{args:?}: input is not null");
assert!(parsed["error"].is_null(), "{args:?}: error is not null");
let result = &parsed["result"];
if expect_list {
let references = result["references"].as_array().expect("a list");
let listed: Vec<&str> = references
.iter()
.map(|entry| entry["name"].as_str().expect("a name"))
.collect();
assert_eq!(listed, reference_names());
for entry in references {
assert!(
!entry["summary"].as_str().expect("a summary").is_empty(),
"an empty summary in the list"
);
}
} else {
assert!(result["name"].is_string(), "{args:?}");
assert!(result["body"].is_string(), "{args:?}");
}
}
let (_, out, _) = run(&["--skill", "-r", "json", "--json"]);
let parsed: serde_json::Value = serde_json::from_str(&out).expect("valid JSON");
assert_eq!(parsed["result"]["name"], "json");
}
#[test]
fn a_bare_invocation_is_still_a_usage_failure() {
let (code, out, err) = run(&[]);
assert_eq!(code, 2);
assert!(out.is_empty(), "usage errors do not go to stdout: {out}");
assert!(err.contains("Usage: matra"), "{err}");
assert!(err.contains("analyze"), "{err}");
}
#[test]
#[ignore = "requires the UDPipe model"]
fn analyze_reports_metrics_and_exits_zero() {
let f = fixture(PROSE, ".txt");
let (code, out, err) = run(&["analyze", path_of(&f)]);
assert_eq!(code, 0, "{err}");
for row in ["sentences", "words", "passive ratio"] {
assert!(out.contains(row), "missing `{row}` in:\n{out}");
}
}
#[test]
#[ignore = "requires the UDPipe model"]
fn sections_adds_the_per_section_breakdown() {
let md = format!("# A Heading\n\n{PROSE}\n\n## Another\n\n{PROSE}\n");
let f = fixture(&md, ".md");
let (code, plain, _) = run(&["analyze", path_of(&f)]);
assert_eq!(code, 0);
assert!(
!plain.contains("A Heading"),
"no breakdown without the flag"
);
let (code, out, err) = run(&["analyze", path_of(&f), "--sections"]);
assert_eq!(code, 0, "{err}");
assert!(out.contains("paragraphs"), "{out}");
assert!(out.contains("A Heading"), "{out}");
assert!(out.contains("Another"), "{out}");
assert!(out.contains("h1"), "{out}");
assert!(out.contains("h2"), "{out}");
}
#[test]
#[ignore = "requires the UDPipe model"]
fn quiet_suppresses_the_table_and_keeps_the_exit_code() {
let f = fixture(PROSE, ".txt");
let (code, out, _) = run(&["analyze", path_of(&f), "--quiet"]);
assert_eq!(code, 0);
assert!(out.is_empty(), "{out}");
let empty = fixture("", ".txt");
let (code, out, _) = run(&["analyze", path_of(&empty), "--quiet"]);
assert_eq!(code, 1, "quiet does not change what was found");
assert!(out.is_empty(), "{out}");
}
#[test]
#[ignore = "requires the UDPipe model"]
fn quiet_does_not_affect_json() {
let f = fixture(PROSE, ".txt");
let (code, quiet, _) = run(&["analyze", path_of(&f), "--json", "--quiet"]);
let (_, loud, _) = run(&["analyze", path_of(&f), "--json"]);
assert_eq!(code, 0);
assert_eq!(quiet, loud);
assert!(!quiet.is_empty());
}
#[test]
#[ignore = "requires the UDPipe model"]
fn color_is_explicit_when_asked_and_absent_when_refused() {
let f = fixture(PROSE, ".txt");
let (_, colored, _) = run(&["analyze", path_of(&f), "--color", "always"]);
let (_, plain, _) = run(&["analyze", path_of(&f), "--color", "never"]);
assert!(colored.contains('\x1b'), "no escapes under --color always");
assert!(!plain.contains('\x1b'), "escapes under --color never");
}
#[test]
#[ignore = "requires the UDPipe model"]
fn empty_input_exits_one_not_two() {
let f = fixture("", ".txt");
let (code, _, _) = run(&["analyze", path_of(&f)]);
assert_eq!(code, 1);
}
#[test]
#[ignore = "requires the UDPipe model"]
fn an_empty_result_says_so_on_stderr() {
let f = fixture("", ".txt");
for (command, said) in [
("summarize", "matra: found nothing to summarize in"),
("keyphrases", "matra: found no keyphrases in"),
] {
let (code, out, err) = run(&[command, path_of(&f)]);
assert_eq!(code, 1, "{command}: {err}");
assert!(out.is_empty(), "{command}: {out}");
assert!(err.contains(said), "{command}: {err}");
let (code, out, err) = run(&[command, path_of(&f), "--json"]);
assert_eq!(code, 1, "{command}: {err}");
assert!(!err.contains("found"), "{command} --json: {err}");
let parsed: serde_json::Value = serde_json::from_str(&out).expect("JSON");
assert!(parsed["error"].is_null());
let (code, _, err) = run(&[command, path_of(&f), "--quiet"]);
assert_eq!(code, 1, "{command}: {err}");
assert!(!err.contains("found"), "{command} --quiet: {err}");
}
}
#[test]
#[ignore = "requires the UDPipe model"]
fn markdown_structure_is_not_ranked_as_prose() {
let md = format!("# A Heading\n\n```bash\ncd somewhere && make install\n```\n\n{PROSE}\n");
let f = fixture(&md, ".md");
let (_, summary, _) = run(&["summarize", path_of(&f), "-n", "3"]);
assert!(
!summary.contains("# A Heading"),
"heading markup ranked as a sentence: {summary}"
);
assert!(
!summary.contains("make install"),
"fenced code ranked as a sentence: {summary}"
);
let (_, phrases, _) = run(&["keyphrases", path_of(&f), "-n", "5"]);
assert!(
!phrases.contains("make install"),
"fenced code produced a keyphrase: {phrases}"
);
}
#[test]
#[ignore = "requires the UDPipe model"]
fn summarize_honours_the_sentence_count() {
let f = fixture(PROSE, ".txt");
let (code, out, err) = run(&["summarize", path_of(&f), "-n", "2"]);
assert_eq!(code, 0, "{err}");
assert_eq!(out.lines().count(), 2, "one line per requested sentence");
}
#[test]
#[ignore = "requires the UDPipe model"]
fn both_summary_methods_run() {
let f = fixture(PROSE, ".txt");
for method in ["tfidf", "textrank"] {
let (code, _, err) = run(&["summarize", path_of(&f), "--method", method]);
assert_eq!(code, 0, "{method}: {err}");
}
}
#[test]
#[ignore = "requires the UDPipe model"]
fn both_keyphrase_methods_run() {
let f = fixture(PROSE, ".txt");
for method in ["rake", "yake"] {
let (code, _, err) = run(&["keyphrases", path_of(&f), "--method", method]);
assert_eq!(code, 0, "{method}: {err}");
}
}
#[test]
#[ignore = "requires the UDPipe model"]
fn every_command_emits_the_same_envelope() {
let f = fixture(PROSE, ".txt");
let path = path_of(&f).to_string();
for (args, command) in [
(vec!["analyze", &path, "--json"], "analyze"),
(vec!["summarize", &path, "--json"], "summarize"),
(vec!["keyphrases", &path, "--json"], "keyphrases"),
] {
let (code, out, err) = run(&args);
assert_eq!(code, 0, "{command}: {err}");
let parsed: serde_json::Value = serde_json::from_str(&out).expect("valid JSON");
let object = parsed.as_object().expect("an object");
let mut keys: Vec<&str> = object.keys().map(String::as_str).collect();
keys.sort_unstable();
assert_eq!(
keys,
["command", "error", "format_version", "input", "result"]
);
assert_eq!(parsed["format_version"], 2);
assert_eq!(parsed["command"], command);
assert_eq!(parsed["input"], path.as_str());
assert!(parsed["error"].is_null(), "{command}");
assert!(parsed["result"].is_object(), "{command}");
}
}
#[test]
#[ignore = "requires the UDPipe model"]
fn a_directory_is_one_envelope_per_line_and_a_failure_does_not_stop_it() {
let dir = tempfile::tempdir().expect("temp dir");
std::fs::write(dir.path().join("a.md"), format!("# Notes\n\n{PROSE}\n")).expect("write");
std::fs::write(dir.path().join("b.bin"), [0xff, 0xfe, 0x00]).expect("write");
std::fs::write(dir.path().join("c.txt"), PROSE).expect("write");
let path = dir.path().to_str().expect("utf8 path");
let (code, out, err) = run(&["analyze", path, "--json"]);
assert_eq!(code, 2, "one file failed: {err}");
let lines: Vec<serde_json::Value> = out
.lines()
.map(|line| serde_json::from_str(line).expect("each line is one envelope"))
.collect();
assert_eq!(lines.len(), 3, "{out}");
let inputs: Vec<&str> = lines
.iter()
.map(|l| l["input"].as_str().expect("each names its file"))
.collect();
for (input, name) in inputs.iter().zip(["a.md", "b.bin", "c.txt"]) {
assert!(input.ends_with(name), "{inputs:?}");
}
assert!(lines[0]["error"].is_null());
document_schema::assert_valid("document", &lines[0]["result"], "a.md");
assert!(lines[1]["result"].is_null());
assert_eq!(lines[1]["error"]["kind"], "unsupported_format");
assert!(
lines[2]["error"].is_null(),
"the walk went on past the failure"
);
assert!(err.contains("b.bin"), "stderr names the failed file: {err}");
let (code, out, _) = run(&["analyze", path]);
assert_eq!(code, 2);
assert!(out.contains("a.md") && out.contains("c.txt"), "{out}");
let empty = tempfile::tempdir().expect("temp dir");
std::fs::write(empty.path().join("a.txt"), "").expect("write");
let (code, _, err) = run(&["analyze", empty.path().to_str().expect("utf8"), "--json"]);
assert_eq!(code, 1, "{err}");
}
#[test]
#[ignore = "requires the UDPipe model"]
fn depth_cuts_the_document_at_the_level_asked_for() {
let f = fixture(&format!("# Notes\n\n{PROSE}\n"), ".md");
let result = |depth: &str| -> serde_json::Value {
let (code, out, err) = run(&["analyze", path_of(&f), "--json", "--depth", depth]);
assert_eq!(code, 0, "{depth}: {err}");
let parsed: serde_json::Value = serde_json::from_str(&out).expect("JSON");
document_schema::assert_valid_at_depth(&parsed["result"], depth);
parsed["result"].clone()
};
let document = result("document");
assert!(document.get("sections").is_none());
assert_eq!(document["metrics"]["total_sentences"], 3);
let paragraph = result("paragraph");
let para = ¶graph["sections"][0]["paragraphs"][0];
assert!(para["text"].is_string());
assert!(para.get("sentences").is_none());
let sentence = result("sentence");
let first = &sentence["sections"][0]["paragraphs"][0]["sentences"][0];
assert!(first["text"].is_string());
assert!(first.get("tokens").is_none());
for depth in ["document", "paragraph", "sentence"] {
let (_, out, _) = run(&["analyze", path_of(&f), "--json", "--depth", depth]);
let envelope: serde_json::Value = serde_json::from_str(&out).expect("JSON");
let text = serde_json::to_string(&envelope["result"]).expect("JSON");
let back: matra::domain::Document = serde_json::from_str(&text)
.unwrap_or_else(|e| panic!("--depth {depth} does not read back: {e}"));
assert_eq!(back.metrics.total_sentences, 3, "{depth}");
}
let token = result("token");
let (_, whole, _) = run(&["analyze", path_of(&f), "--json"]);
let whole: serde_json::Value = serde_json::from_str(&whole).expect("JSON");
assert_eq!(
token, whole["result"],
"token is the default, and everything"
);
let keys = |value: &serde_json::Value| -> Vec<String> {
value
.as_object()
.expect("an object")
.keys()
.cloned()
.collect()
};
let whole_paragraph = &whole["result"]["sections"][0]["paragraphs"][0];
let mut expected = keys(whole_paragraph);
expected.retain(|k| k != "sentences");
assert_eq!(keys(para), expected, "a paragraph at --depth paragraph");
let mut sorted = keys(whole_paragraph);
sorted.sort();
assert_ne!(
keys(whole_paragraph),
sorted,
"declaration order, not sorted"
);
}
#[test]
#[ignore = "requires the UDPipe model"]
fn format_reads_a_file_as_the_format_named() {
let f = fixture(
r#"[{"kind": "heading", "level": 1, "text": "Field notes"},
{"kind": "paragraph", "text": "The river rose overnight."}]"#,
".json",
);
let (code, out, err) = run(&["analyze", path_of(&f), "--format", "blocks", "--json"]);
assert_eq!(code, 0, "{err}");
let parsed: serde_json::Value = serde_json::from_str(&out).expect("JSON");
assert_eq!(parsed["result"]["provenance"]["format"], "blocks");
assert_eq!(parsed["result"]["sections"][0]["heading"], "Field notes");
let (_, out, _) = run(&["analyze", path_of(&f), "--json"]);
let parsed: serde_json::Value = serde_json::from_str(&out).expect("JSON");
assert_eq!(parsed["result"]["provenance"]["format"], "plain_text");
}
#[cfg(feature = "model2vec")]
#[test]
#[ignore = "requires the UDPipe and potion-base-8M models"]
fn clusters_groups_sentences_by_meaning() {
let f = fixture(
"The committee approved the proposal without debate. \
The weather turned cold by evening. \
The proposal was approved by the committee with no discussion.",
".txt",
);
let (code, out, err) = run(&["clusters", path_of(&f), "--json"]);
assert_eq!(code, 0, "{err}");
let parsed: serde_json::Value = serde_json::from_str(&out).expect("JSON");
assert_eq!(parsed["command"], "clusters");
document_schema::assert_valid("clusters", &parsed["result"], "matra clusters");
assert_eq!(
parsed["result"]["clusters"][0]["members"],
serde_json::json!([0, 2])
);
assert_eq!(
parsed["result"]["provenance"]["parameters"]["threshold"],
0.85
);
let (code, out, err) = run(&["clusters", path_of(&f), "--threshold", "0.999"]);
assert_eq!(code, 1, "{err}");
assert!(out.is_empty(), "{out}");
assert!(
err.contains("matra: found no clusters in") && err.contains("at --threshold 0.999"),
"{err}"
);
assert!(err.contains("a lower threshold"), "{err}");
}
#[cfg(not(feature = "model2vec"))]
#[test]
fn clusters_without_an_embedder_says_which_feature_ships_one() {
let f = fixture(PROSE, ".txt");
let (code, out, err) = run(&["clusters", path_of(&f), "--json"]);
assert_eq!(code, 2);
assert!(err.contains("model2vec"), "{err}");
let parsed: serde_json::Value = serde_json::from_str(&out).expect("JSON");
assert_eq!(parsed["error"]["kind"], "invalid_input");
}
#[test]
#[ignore = "requires the UDPipe model"]
fn the_result_is_the_domain_value_unchanged() {
let f = fixture(PROSE, ".txt");
let (_, out, _) = run(&["analyze", path_of(&f), "--json"]);
let parsed: serde_json::Value = serde_json::from_str(&out).expect("valid JSON");
let result = &parsed["result"];
assert!(result["sections"].is_array());
assert!(
result["sections"][0]["paragraphs"][0]["sentences"][0]["tokens"][0]["lemma"].is_string(),
"token lemma reachable at the documented path"
);
document_schema::assert_valid("document", result, "analyze --json");
}
#[test]
#[ignore = "requires the UDPipe model"]
fn envelope_matches_the_conformance_fixture() {
let spec: serde_json::Value = serde_json::from_str(
&std::fs::read_to_string(
Path::new(env!("CARGO_MANIFEST_DIR")).join("spec/tests/cli/envelope.json"),
)
.expect("read fixture"),
)
.expect("fixture parses");
let dir = tempfile::tempdir().expect("temp dir");
let path = dir
.path()
.join(spec["filename"].as_str().expect("filename"));
std::fs::write(&path, spec["input"].as_str().expect("input")).expect("write input");
let path = path.to_str().expect("utf8 path").to_string();
let mut args: Vec<&str> = vec![spec["args"][0].as_str().expect("subcommand"), &path];
args.push(spec["args"][1].as_str().expect("flag"));
let (code, out, err) = run(&args);
assert_eq!(code, 0, "{err}");
let got: serde_json::Value = serde_json::from_str(&out).expect("valid JSON");
let expect = &spec["expect"];
let mut keys: Vec<&str> = got
.as_object()
.expect("object")
.keys()
.map(String::as_str)
.collect();
keys.sort_unstable();
assert_eq!(serde_json::json!(keys), expect["envelope_keys"]);
assert_eq!(got["format_version"], expect["format_version"]);
assert_eq!(got["command"], expect["command"]);
assert_eq!(got["input"], serde_json::json!(path));
let mut result_keys: Vec<&str> = got["result"]
.as_object()
.expect("object")
.keys()
.map(String::as_str)
.collect();
result_keys.sort_unstable();
assert_eq!(serde_json::json!(result_keys), expect["result_keys"]);
assert_eq!(got["result"]["provenance"]["schema"], expect["schema"]);
assert_eq!(got["result"]["provenance"]["format"], expect["format"]);
assert_eq!(
got["result"]["metrics"]["total_sentences"],
expect["result_sentences"]
);
document_schema::assert_valid("document", &got["result"], "the envelope fixture");
let sections = got["result"]["sections"].as_array().expect("sections");
assert_eq!(serde_json::json!(sections.len()), expect["result_sections"]);
let sentences: usize = sections
.iter()
.flat_map(|s| s["paragraphs"].as_array().expect("paragraphs"))
.map(|p| p["sentences"].as_array().expect("sentences").len())
.sum();
assert_eq!(serde_json::json!(sentences), expect["result_sentences"]);
}
#[test]
fn config_show_reports_where_every_value_came_from() {
let home = tempfile::tempdir().expect("temp dir");
let out = scoped(home.path())
.args(["config", "show"])
.assert()
.code(0)
.get_output()
.stdout
.clone();
let out = String::from_utf8(out).expect("utf8");
for key in [
"data_dir",
"model_dir",
"models.embedding",
"summary.n",
"summary.method",
"keyphrases.n",
"keyphrases.method",
"clusters.threshold",
] {
assert!(out.contains(key), "missing `{key}` in:\n{out}");
}
for line in out.lines() {
assert!(line.contains(" # "), "no origin on: {line}");
}
assert!(out.contains("default"), "{out}");
let out = scoped(home.path())
.env("MATRA_DATA_DIR", home.path().join("elsewhere"))
.args(["config", "show"])
.assert()
.code(0)
.get_output()
.stdout
.clone();
let out = String::from_utf8(out).expect("utf8");
assert!(out.contains("MATRA_DATA_DIR"), "{out}");
}
#[test]
fn config_show_names_the_file_it_read_or_null() {
let home = tempfile::tempdir().expect("temp dir");
let envelope = |home: &Path| -> serde_json::Value {
let out = scoped(home)
.args(["config", "show", "--json"])
.assert()
.code(0)
.get_output()
.stdout
.clone();
serde_json::from_slice(&out).expect("one JSON object")
};
let none = envelope(home.path());
let mut keys: Vec<&str> = none
.as_object()
.expect("an object")
.keys()
.map(String::as_str)
.collect();
keys.sort_unstable();
assert_eq!(
keys,
["command", "error", "format_version", "input", "result"]
);
assert_eq!(none["command"], "config");
assert!(none["input"].is_null(), "no config file was read: {none}");
assert!(none["error"].is_null());
let target = home.path().join("config").join("matra").join("config.toml");
std::fs::create_dir_all(target.parent().expect("a parent")).expect("config dir");
std::fs::write(&target, "[summary]\nn = 5\n").expect("write the file");
let read = envelope(home.path());
assert_eq!(read["input"], target.display().to_string());
assert_eq!(read["result"]["summary.n"]["value"], 5);
}
#[test]
fn config_init_writes_once_and_refuses_without_force() {
let home = tempfile::tempdir().expect("temp dir");
let target = home.path().join("config").join("matra").join("config.toml");
scoped(home.path())
.args(["config", "init"])
.assert()
.code(0)
.stdout(predicate::str::contains("config.toml"));
let written = std::fs::read_to_string(&target).expect("the file exists");
for section in ["[models]", "[summary]", "[keyphrases]", "[clusters]"] {
assert!(written.contains(section), "{section} missing:\n{written}");
}
for old in ["udpipe", "[semantic]", "[summarize]", "algorithm"] {
assert!(!written.contains(old), "{old} written:\n{written}");
}
scoped(home.path())
.args(["config", "init"])
.assert()
.code(2)
.stderr(predicate::str::contains("--force"));
scoped(home.path())
.args(["config", "init", "--force"])
.assert()
.code(0);
assert_eq!(
std::fs::read_to_string(&target).expect("still there"),
written
);
}
#[test]
fn a_written_config_becomes_the_source() {
let home = tempfile::tempdir().expect("temp dir");
scoped(home.path())
.args(["config", "init"])
.assert()
.code(0);
let out = scoped(home.path())
.args(["config", "show"])
.assert()
.code(0)
.get_output()
.stdout
.clone();
let out = String::from_utf8(out).expect("utf8");
assert!(out.contains("config.toml"), "{out}");
}
const CONFIG_FROM_0_2: &str = r#"[models]
# Model directory defaults to $XDG_DATA_HOME/matra/models (~/.local/share/matra/models).
# Override with MATRA_MODEL_DIR, or MATRA_DATA_DIR for the whole data root.
udpipe = "english-ewt-ud-2.5-191206"
embedding = "potion-base-8M"
[semantic]
threshold = 0.85
[summarize]
n = 3
algorithm = "tfidf"
[keyphrases]
n = 10
algorithm = "rake"
"#;
#[test]
fn a_config_file_from_0_2_fails_naming_the_new_keys() {
let home = tempfile::tempdir().expect("temp dir");
let target = home.path().join("config").join("matra").join("config.toml");
std::fs::create_dir_all(target.parent().expect("a parent")).expect("config dir");
std::fs::write(&target, CONFIG_FROM_0_2).expect("write the old file");
let output = scoped(home.path())
.args(["config", "show"])
.assert()
.code(2)
.get_output()
.clone();
let err = String::from_utf8(output.stderr).expect("utf8");
assert!(output.stdout.is_empty(), "nothing on stdout without --json");
for named in [
target.display().to_string().as_str(),
"`[summary]`",
"`summary.method`",
"`keyphrases.method`",
"`clusters.threshold`",
"`models.udpipe`",
] {
assert!(err.contains(named), "{named} not named:\n{err}");
}
let output = scoped(home.path())
.args(["config", "show", "--json"])
.assert()
.code(2)
.get_output()
.clone();
let json: serde_json::Value = serde_json::from_slice(&output.stdout).expect("one JSON object");
assert!(json["result"].is_null());
assert_eq!(json["error"]["kind"], "invalid_input");
}
#[test]
#[ignore = "requires the UDPipe model"]
fn stdin_is_read_from_dash_and_labelled_by_stdin_filename() {
let md = format!("# A Heading\n\n{PROSE}\n");
let out = Command::cargo_bin("matra")
.expect("binary built with --features cli")
.args(["analyze", "-", "--stdin-filename", "notes.md", "--json"])
.write_stdin(md)
.assert()
.code(0)
.get_output()
.stdout
.clone();
let parsed: serde_json::Value =
serde_json::from_slice(&out).expect("stdout is the JSON envelope");
assert_eq!(parsed["input"], "notes.md");
assert_eq!(parsed["result"]["sections"][0]["heading"], "A Heading");
}
#[test]
#[ignore = "requires the UDPipe model"]
fn stdin_is_bytes_detected_like_a_file() {
let output = Command::cargo_bin("matra")
.expect("binary built with --features cli")
.args(["analyze", "-", "--json"])
.write_stdin(vec![0xff, 0xfe, 0x00])
.assert()
.code(2)
.get_output()
.clone();
let parsed: serde_json::Value =
serde_json::from_slice(&output.stdout).expect("stdout is the JSON envelope");
assert_eq!(parsed["input"], "<stdin>");
assert_eq!(parsed["error"]["kind"], "unsupported_format");
let out = Command::cargo_bin("matra")
.expect("binary built with --features cli")
.args(["analyze", "-", "--format", "markdown", "--json"])
.write_stdin(format!("# A Heading\n\n{PROSE}\n"))
.assert()
.code(0)
.get_output()
.stdout
.clone();
let parsed: serde_json::Value = serde_json::from_slice(&out).expect("JSON");
assert_eq!(parsed["result"]["provenance"]["format"], "markdown");
assert_eq!(parsed["result"]["sections"][0]["heading"], "A Heading");
}