Skip to content

Commit 47f8a50

Browse files
committed
fix(cli): report a piped document's findings on stdout like every other run
`--stderr` is documented as writing diagnostics "to stderr instead of stdout", and a run over file arguments honors it. `check --stdin` ignored it and forced stderr, so the same findings arrived on a different stream depending only on whether the document came from a path or a pipe. The consequence is silent for a machine-readable format: `check --stdin --output-format json > findings.json` wrote an empty file and exited 1, which reads as a run that found nothing. Nothing reaches stdout in check mode for the diagnostics to collide with; only fix and format modes put a rewritten document there, and those already report through their own stderr writer. A closing summary is a sentence for a person, and the stdin path emitted one whatever the format was asked for. That was invisible while the diagnostics shared stderr with it and nothing read that stream; moving them to stdout put the sentence inside the output a caller redirects. Fix mode has the same defect against stderr, where its own rewritten document leaves the diagnostics. A run over file arguments suppresses the summary for every machine-readable format; both stdin paths now do the same, so `json`, `json-lines`, `sarif`, `junit`, `github`, `gitlab`, `azure` and `pylint` stay parseable without `--quiet`. Human formats keep their summary. The tests covering this asserted the old stream, `assert_eq!(stdout, "")` standing in for "check mode does not emit the fixed document". That guarantee is now checked directly, and the stream contract has tests of its own: JSON on stdout, per-line parseability for `json-lines`, `--stderr` moving the same text, the fix-mode streams checked the same way, and `fmt --stdin` still handing stdout to the document.
1 parent fdc8f3d commit 47f8a50

4 files changed

Lines changed: 237 additions & 42 deletions

File tree

‎docs/usage/cli.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,8 +33,18 @@ rumdl check --fix . # Lint and auto-fix issues
3333
| `--quiet` | Print diagnostics, but suppress summaries |
3434
| `--silent` | Suppress diagnostics and summaries |
3535
| `--no-exclude` | Disable exclude patterns defined in config |
36+
| `--stderr` | Write diagnostics to stderr instead of stdout |
3637
| `--deny-config-warnings` | Treat configuration warnings as errors (exit code 2) |
3738

39+
Findings go to stdout, whether the document came from a path or from `--stdin`,
40+
so `--output-format json` redirects the same way in both. `--stderr` moves them;
41+
config warnings and errors are always on stderr. The exception is a document
42+
rewritten on stdout - `check --fix --stdin` and `fmt --stdin` - where stdout
43+
belongs to the document and diagnostics go to stderr.
44+
45+
The closing summary is written for a person, so a machine-readable format never
46+
carries one and needs no `--quiet` to keep its output parseable.
47+
3848
### `fmt [PATHS...]`
3949

4050
Format Markdown files (applies fixes like `rumdl check --fix`, but keeps formatter-style exit codes).

‎src/stdin_processor.rs‎

Lines changed: 15 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -208,15 +208,11 @@ pub fn process_stdin(
208208
let quiet = args.quiet;
209209
let silent = args.silent;
210210

211-
// In check mode, diagnostics go to stderr by default
212-
// In fix/format modes, fixed content goes to stdout, so diagnostics go to stdout unless --stderr is specified
213-
let use_stderr = if args.fix_mode != crate::FixMode::Check {
214-
args.stderr
215-
} else {
216-
true
217-
};
218-
// Create output writer for linting results
219-
let output_writer = OutputWriter::new(use_stderr, silent);
211+
// Diagnostics are what `check` was asked to produce, so they go to stdout
212+
// unless --stderr moves them, exactly as they do for a run over file
213+
// arguments. Fix and format modes put the rewritten document on stdout
214+
// instead and write their diagnostics through a separate stderr writer.
215+
let output_writer = OutputWriter::new(args.stderr, silent);
220216

221217
let output_format = match crate::cli_utils::resolve_output_format(args, config) {
222218
Ok(fmt) => fmt,
@@ -479,7 +475,10 @@ pub fn process_stdin(
479475
}
480476
}
481477
}
482-
if !quiet {
478+
// Stdout holds the rewritten document here, so this stream is
479+
// where a machine-readable format is read from, and prose ends
480+
// it the same way it would end stdout in check mode.
481+
if !quiet && !output_format.is_machine_readable() {
483482
fix_writer
484483
.writeln(&format!(
485484
"\n{} issue(s) fixed, {} issue(s) remaining",
@@ -544,8 +543,12 @@ pub fn process_stdin(
544543
});
545544
}
546545

547-
// Print summary if not quiet
548-
if !quiet {
546+
// The summary is a sentence for a person, so it is emitted only for the
547+
// formats a person reads. A streaming machine-readable format shares
548+
// stdout with the diagnostics it just wrote, and appending prose there
549+
// makes the document unparseable, exactly as it would for a run over
550+
// file arguments.
551+
if !quiet && !output_format.is_machine_readable() {
549552
if has_issues {
550553
output_writer
551554
.writeln(&format!(

‎tests/cli/cli_integration_tests.rs‎

Lines changed: 206 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -2051,17 +2051,204 @@ fn test_stdin_check_without_fix() {
20512051
let stdout = String::from_utf8_lossy(&output.stdout);
20522052
let stderr = String::from_utf8_lossy(&output.stderr);
20532053

2054-
// Should not output content to stdout in check mode
2055-
assert_eq!(stdout, "");
2056-
// Should report issues on stderr
2057-
assert!(stderr.contains("MD009"));
2058-
assert!(stderr.contains("trailing spaces"));
2054+
// The findings are the answer, so they are on stdout as they are for a run
2055+
// over file arguments.
2056+
assert!(stdout.contains("MD009"), "got stdout:\n{stdout}");
2057+
assert!(stdout.contains("trailing spaces"));
20592058
// MD047 is also triggered since input doesn't end with newline
2060-
assert!(stderr.contains("Found 3 issue(s)"));
2059+
assert!(stdout.contains("Found 3 issue(s)"));
2060+
assert_eq!(stderr, "", "check mode leaves stderr for problems");
2061+
// Check mode never rewrites the document, so the fixed form must not appear.
2062+
assert!(
2063+
!stdout.contains("# Test\n"),
2064+
"check mode must not emit fixed content, got stdout:\n{stdout}"
2065+
);
20612066
// Should exit with error due to issues
20622067
assert!(!output.status.success());
20632068
}
20642069

2070+
/// Run rumdl with `args`, piping `input` to stdin, and return (stdout, stderr).
2071+
fn run_piped(args: &[&str], input: &str) -> (String, String) {
2072+
use std::io::Write;
2073+
use std::process::Stdio;
2074+
2075+
let mut child = Command::new(env!("CARGO_BIN_EXE_rumdl"))
2076+
.args(args)
2077+
.stdin(Stdio::piped())
2078+
.stdout(Stdio::piped())
2079+
.stderr(Stdio::piped())
2080+
.spawn()
2081+
.expect("failed to spawn rumdl");
2082+
child
2083+
.stdin
2084+
.take()
2085+
.expect("stdin was piped")
2086+
.write_all(input.as_bytes())
2087+
.expect("failed to write to stdin");
2088+
let output = child.wait_with_output().expect("failed to wait for rumdl");
2089+
(
2090+
String::from_utf8_lossy(&output.stdout).into_owned(),
2091+
String::from_utf8_lossy(&output.stderr).into_owned(),
2092+
)
2093+
}
2094+
2095+
#[test]
2096+
fn stdin_check_writes_machine_readable_output_to_stdout() {
2097+
// Redirecting stdout is how a machine-readable format is consumed, so the
2098+
// document a caller pipes in must not change which stream carries it.
2099+
let (stdout, stderr) = run_piped(
2100+
&[
2101+
"check",
2102+
"--no-cache",
2103+
"--no-config",
2104+
"--stdin",
2105+
"--output-format",
2106+
"json",
2107+
],
2108+
"# Test \n",
2109+
);
2110+
2111+
let parsed: serde_json::Value = serde_json::from_str(stdout.trim())
2112+
.unwrap_or_else(|e| panic!("stdout must be the JSON document: {e}, got stdout:\n{stdout}"));
2113+
assert_eq!(
2114+
parsed.as_array().map(Vec::len),
2115+
Some(1),
2116+
"the trailing-space finding is the whole document, got:\n{stdout}"
2117+
);
2118+
assert_eq!(parsed[0]["rule"], "MD009");
2119+
assert_eq!(stderr, "", "nothing is left on stderr to be lost");
2120+
}
2121+
2122+
#[test]
2123+
fn stdin_check_keeps_prose_out_of_a_streaming_machine_format() {
2124+
// A batch format writes one document and stops, but a streaming format ends
2125+
// wherever the last finding did, so a trailing summary lands inside the
2126+
// output a caller redirects. Every line of it has to stay machine-readable.
2127+
for format in ["json-lines", "github", "azure", "pylint"] {
2128+
let (stdout, stderr) = run_piped(
2129+
&[
2130+
"check",
2131+
"--no-cache",
2132+
"--no-config",
2133+
"--stdin",
2134+
"--output-format",
2135+
format,
2136+
],
2137+
"# Test \n",
2138+
);
2139+
2140+
assert!(
2141+
stdout.contains("MD009"),
2142+
"{format} must still report the finding, got stdout:\n{stdout}"
2143+
);
2144+
assert!(
2145+
!stdout.contains("Found 1 issue"),
2146+
"{format} carries no summary prose, got stdout:\n{stdout}"
2147+
);
2148+
assert_eq!(stderr, "", "{format} leaves stderr for problems");
2149+
}
2150+
2151+
// json-lines is the one whose whole contract is per-line parseability, so
2152+
// check that rather than trusting the absence of one sentence.
2153+
let (stdout, _) = run_piped(
2154+
&[
2155+
"check",
2156+
"--no-cache",
2157+
"--no-config",
2158+
"--stdin",
2159+
"--output-format",
2160+
"json-lines",
2161+
],
2162+
"# Test \n",
2163+
);
2164+
for line in stdout.lines().filter(|l| !l.trim().is_empty()) {
2165+
serde_json::from_str::<serde_json::Value>(line)
2166+
.unwrap_or_else(|e| panic!("every json-lines line is a JSON object: {e}, got line:\n{line}"));
2167+
}
2168+
2169+
// The control: a human format still gets the sentence, so the suppression
2170+
// tracks the format rather than switching the summary off everywhere.
2171+
let (human_stdout, _) = run_piped(&["check", "--no-cache", "--no-config", "--stdin"], "# Test \n");
2172+
assert!(
2173+
human_stdout.contains("Found 1 issue"),
2174+
"the default format keeps its summary, got stdout:\n{human_stdout}"
2175+
);
2176+
}
2177+
2178+
#[test]
2179+
fn stdin_check_moves_findings_to_stderr_on_request() {
2180+
// The control for the default above: --stderr is what redirects them, and
2181+
// it means the stream choice is a decision rather than an accident.
2182+
let args = ["check", "--no-cache", "--no-config", "--stdin", "--quiet"];
2183+
let (default_out, default_err) = run_piped(&args, "# Test \n");
2184+
let (moved_out, moved_err) = run_piped(&[args.as_slice(), ["--stderr"].as_slice()].concat(), "# Test \n");
2185+
2186+
assert!(default_out.contains("MD009"), "got stdout:\n{default_out}");
2187+
assert_eq!(default_err, "");
2188+
assert_eq!(moved_out, "");
2189+
assert_eq!(
2190+
moved_err, default_out,
2191+
"--stderr moves the same text rather than producing different text"
2192+
);
2193+
}
2194+
2195+
#[test]
2196+
fn stdin_fmt_keeps_stdout_for_the_document() {
2197+
// Fix and format modes are the reason the check-mode stream was ever in
2198+
// question: there stdout carries the rewritten document.
2199+
let (stdout, stderr) = run_piped(&["fmt", "--no-cache", "--no-config", "--stdin"], "#Heading\n");
2200+
2201+
assert_eq!(stdout, "# Heading\n", "got stderr:\n{stderr}");
2202+
}
2203+
2204+
#[test]
2205+
fn stdin_fix_keeps_prose_out_of_a_machine_format() {
2206+
// In fix mode the rewritten document owns stdout, so stderr is where a
2207+
// machine-readable format is read from and the same rule applies to it.
2208+
// MD009 is fixable and MD045 is not, so a summary has something to report.
2209+
let input = "# Test \n\n![](img.png)\n";
2210+
2211+
let (stdout, stderr) = run_piped(
2212+
&[
2213+
"check",
2214+
"--fix",
2215+
"--no-cache",
2216+
"--no-config",
2217+
"--stdin",
2218+
"--output-format",
2219+
"json",
2220+
],
2221+
input,
2222+
);
2223+
assert_eq!(stdout, "# Test\n\n![](img.png)\n", "stdout is the fixed document");
2224+
let parsed: serde_json::Value = serde_json::from_str(stderr.trim())
2225+
.unwrap_or_else(|e| panic!("stderr must be the JSON document: {e}, got stderr:\n{stderr}"));
2226+
assert_eq!(parsed[0]["rule"], "MD045", "the unfixable finding remains");
2227+
2228+
let (_, stderr) = run_piped(
2229+
&[
2230+
"fmt",
2231+
"--no-cache",
2232+
"--no-config",
2233+
"--stdin",
2234+
"--output-format",
2235+
"json-lines",
2236+
],
2237+
input,
2238+
);
2239+
for line in stderr.lines().filter(|l| !l.trim().is_empty()) {
2240+
serde_json::from_str::<serde_json::Value>(line)
2241+
.unwrap_or_else(|e| panic!("every json-lines line is a JSON object: {e}, got line:\n{line}"));
2242+
}
2243+
2244+
// The control: the default format still reports what the fix did.
2245+
let (_, human_stderr) = run_piped(&["fmt", "--no-cache", "--no-config", "--stdin"], input);
2246+
assert!(
2247+
human_stderr.contains("issue(s) remaining"),
2248+
"the default format keeps its summary, got stderr:\n{human_stderr}"
2249+
);
2250+
}
2251+
20652252
#[test]
20662253
fn test_stdin_formatting_no_issues() {
20672254
let rumdl_exe = env!("CARGO_BIN_EXE_rumdl");
@@ -2118,12 +2305,10 @@ fn test_stdin_dash_syntax() {
21182305
let stdout = String::from_utf8_lossy(&output.stdout);
21192306
let stderr = String::from_utf8_lossy(&output.stderr);
21202307

2121-
// Should not output content to stdout in check mode
2122-
assert_eq!(stdout, "");
2123-
// Should report issues on stderr
2124-
assert!(stderr.contains("MD009"));
2125-
assert!(stderr.contains("trailing spaces"));
2126-
assert!(stderr.contains("Found 3 issue(s)"));
2308+
assert!(stdout.contains("MD009"), "got stdout:\n{stdout}");
2309+
assert!(stdout.contains("trailing spaces"));
2310+
assert!(stdout.contains("Found 3 issue(s)"));
2311+
assert_eq!(stderr, "", "check mode leaves stderr for problems");
21272312
}
21282313

21292314
#[test]
@@ -2150,20 +2335,19 @@ fn test_stdin_filename_flag() {
21502335
let stdout = String::from_utf8_lossy(&output.stdout);
21512336
let stderr = String::from_utf8_lossy(&output.stderr);
21522337

2153-
// Should not output content to stdout in check mode
2154-
assert_eq!(stdout, "");
21552338
// Should show the custom filename in error messages
21562339
assert!(
2157-
stderr.contains("test-file.md:1:"),
2158-
"Error message should contain custom filename"
2340+
stdout.contains("test-file.md:1:"),
2341+
"Error message should contain custom filename, got stdout:\n{stdout}"
21592342
);
21602343
assert!(
2161-
stderr.contains("test-file.md:3:"),
2344+
stdout.contains("test-file.md:3:"),
21622345
"Error message should contain custom filename for line 3"
21632346
);
2164-
assert!(stderr.contains("in test-file.md"), "Summary should use custom filename");
2347+
assert!(stdout.contains("in test-file.md"), "Summary should use custom filename");
21652348
// Should still detect the issues
2166-
assert!(stderr.contains("MD009"));
2349+
assert!(stdout.contains("MD009"));
2350+
assert_eq!(stderr, "", "check mode leaves stderr for problems");
21672351
}
21682352

21692353
#[test]
@@ -3659,14 +3843,14 @@ fn test_stdin_inline_disable_next_line_is_scoped() {
36593843
drop(stdin);
36603844

36613845
let output = child.wait_with_output().expect("Failed to wait for command");
3662-
let stderr = String::from_utf8_lossy(&output.stderr);
3846+
let stdout = String::from_utf8_lossy(&output.stdout);
36633847

3664-
let md009_warnings: Vec<&str> = stderr.lines().filter(|l| l.contains("MD009")).collect();
3848+
let md009_warnings: Vec<&str> = stdout.lines().filter(|l| l.contains("MD009")).collect();
36653849

36663850
assert_eq!(
36673851
md009_warnings.len(),
36683852
1,
3669-
"Expected exactly 1 MD009 warning (line 5 only), got {}: {stderr}",
3853+
"Expected exactly 1 MD009 warning (line 5 only), got {}: {stdout}",
36703854
md009_warnings.len()
36713855
);
36723856
assert!(

‎tests/config/editorconfig_test.rs‎

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -247,13 +247,11 @@ fn stdin_named_as_a_file_gets_that_file_s_editorconfig() {
247247
"the file on disk is the reference this content is compared against"
248248
);
249249

250-
// Reading stdin keeps stdout for the content itself, so the findings are on
251-
// stderr here rather than where file mode puts them.
252250
let piped = check_stdin(temp.path(), &content, &["--stdin-filename", "doc.md"]);
253251
assert!(
254-
stderr(&piped).contains(expected),
255-
"the same content named as the same file must lint the same way, got stderr:\n{}",
256-
stderr(&piped)
252+
stdout(&piped).contains(expected),
253+
"the same content named as the same file must lint the same way, got stdout:\n{}",
254+
stdout(&piped)
257255
);
258256
}
259257

@@ -268,9 +266,9 @@ fn stdin_without_a_filename_has_no_editorconfig_to_resolve() {
268266

269267
let out = check_stdin(temp.path(), &format!("# Title\n\n{LONG_LINE}\n"), &[]);
270268
assert!(
271-
!stderr(&out).contains("MD013"),
272-
"there is no file to resolve properties for, got stderr:\n{}",
273-
stderr(&out)
269+
!stdout(&out).contains("MD013"),
270+
"there is no file to resolve properties for, got stdout:\n{}",
271+
stdout(&out)
274272
);
275273
}
276274

0 commit comments

Comments
 (0)