From cf4f0be12dd63c771bc1f973b1b693c0de828b70 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 29 Sep 2026 15:57:40 +0200 Subject: [PATCH] feat: add structured detector output modes --- Cargo.lock | 26 ++ Cargo.toml | 1 + docs/usage.md | 7 + src/bin/john-slop.rs | 33 ++- src/bin/john-slop/output.rs | 237 ++++++++++++++++++ src/model.rs | 21 +- tasks.md | 2 +- ...p_is_successful_and_names_the_command.snap | 2 + 8 files changed, 317 insertions(+), 12 deletions(-) create mode 100644 src/bin/john-slop/output.rs diff --git a/Cargo.lock b/Cargo.lock index 9763d68..e7a0174 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -565,6 +565,12 @@ version = "1.2.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "7655c9839580ee829dfacba1d1278c2b7883e50a277ff7541299489d6bdfdc45" +[[package]] +name = "itoa" +version = "1.0.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + [[package]] name = "jobserver" version = "0.1.35" @@ -587,6 +593,7 @@ dependencies = [ "miette", "regex", "serde", + "serde_json", "tempfile", "thiserror", "toml 1.1.6+spec-1.1.0", @@ -903,6 +910,19 @@ dependencies = [ "syn 3.0.6", ] +[[package]] +name = "serde_json" +version = "1.0.151" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14" +dependencies = [ + "itoa", + "memchr", + "serde", + "serde_core", + "zmij", +] + [[package]] name = "serde_spanned" version = "0.6.9" @@ -1470,6 +1490,12 @@ version = "0.6.8" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b268e58e7c693d7c271f93ffc4ba3b380412554231c85bf61ca7af91042a4112" +[[package]] +name = "zmij" +version = "1.0.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b" + [[package]] name = "zopfli" version = "0.8.3" diff --git a/Cargo.toml b/Cargo.toml index b34053d..7a492f3 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -31,6 +31,7 @@ globset = { version = "0.4.20", default-features = false } miette = { version = "7.6.0", default-features = false, features = ["derive"] } regex = "1.13.1" serde = { version = "1.0.229", features = ["derive"] } +serde_json = "1.0.151" thiserror = "2.0.21" toml = "1.1.6" walkdir = "2.5.0" diff --git a/docs/usage.md b/docs/usage.md index 4660324..4b97e60 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -22,6 +22,13 @@ limits can be overridden with `--max-document-bytes`, `--max-archive-bytes`, `--max-expanded-bytes`, `--max-archive-entries`, `--max-compression-ratio`, and `--max-walk-depth`. +Select output with `--output human`, `--output concise`, or `--output json`. +Human mode renders plain source excerpts, exact labels, remediation help, and a +summary. Concise mode emits stable single-line finding and summary records. JSON +mode emits one object per analyzed document with `schema_version: 1`, summary +fields, exact byte spans, and every finding. Machine modes never emit ANSI +escapes or logs on stdout. + The current human-readable output contains the source identity, bounded evidence confidence, and finding count. Findings cover the embedded or overridden heuristic catalog and retain exact UTF-8 byte spans for later presentation. diff --git a/src/bin/john-slop.rs b/src/bin/john-slop.rs index c5b0ab3..8ec82fa 100644 --- a/src/bin/john-slop.rs +++ b/src/bin/john-slop.rs @@ -1,5 +1,8 @@ //! Detector command-line adapter. +#[path = "john-slop/output.rs"] +mod output; + use std::{ path::{Path, PathBuf}, process::ExitCode, @@ -13,6 +16,8 @@ use john_slop::{ }; use miette::{IntoDiagnostic, Result, WrapErr}; +use output::{OutputFormat, render_analysis}; + /// Inspect files, directories, or ZIP-based documents for low-care signals. #[derive(Debug, Parser)] #[command( @@ -68,6 +73,16 @@ struct Cli { #[arg(long, value_name = "GLOB", action = clap::ArgAction::Append)] ignore: Vec, + /// Select human, concise, or versioned JSON output. + #[arg( + long, + value_enum, + default_value_t, + value_name = "human|concise|json", + hide_possible_values = true + )] + output: OutputFormat, + /// Return exit code 1 when a document reaches this evidence-confidence score. #[arg(long, default_value_t = 100, value_parser = parse_confidence)] fail_confidence: u8, @@ -154,11 +169,10 @@ fn run(cli: &Cli) -> Result { }); if !is_ignored(&ignore, cli.stdin_filename.as_deref()) { let analysis = detector.analyze_with(&document.content, &context); - println!( - "{}: confidence {}, {} finding(s)", - document.source, - analysis.confidence.score(), - analysis.findings.len() + print!( + "{}", + render_analysis(cli.output, &document.source, &document.content, &analysis) + .into_diagnostic()? ); threshold_reached |= analysis.confidence.score() >= cli.fail_confidence; } @@ -177,11 +191,10 @@ fn run(cli: &Cli) -> Result { } let context = john_slop::AnalysisContext::for_source(&document.source); let analysis = detector.analyze_with(&document.content, &context); - println!( - "{}: confidence {}, {} finding(s)", - document.source, - analysis.confidence.score(), - analysis.findings.len() + print!( + "{}", + render_analysis(cli.output, &document.source, &document.content, &analysis) + .into_diagnostic()? ); threshold_reached |= analysis.confidence.score() >= cli.fail_confidence; } diff --git a/src/bin/john-slop/output.rs b/src/bin/john-slop/output.rs new file mode 100644 index 0000000..ac52ccf --- /dev/null +++ b/src/bin/john-slop/output.rs @@ -0,0 +1,237 @@ +//! Deterministic detector output renderers. + +use clap::ValueEnum; +use john_slop::{Analysis, Finding, FindingDiagnostic, SourceId}; +use miette::NarratableReportHandler; +use serde::Serialize; + +/// User-selectable detector presentation format. +#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, ValueEnum)] +pub enum OutputFormat { + /// Plain source-highlighted diagnostics followed by a document summary. + #[default] + Human, + /// One stable single-line record per finding plus one summary record. + Concise, + /// One versioned JSON object per analyzed document. + Json, +} + +pub(super) fn render_analysis( + format: OutputFormat, + source_id: &SourceId, + source: &str, + analysis: &Analysis, +) -> Result { + match format { + OutputFormat::Human => Ok(render_human(source_id, source, analysis)), + OutputFormat::Concise => Ok(render_concise(source_id, analysis)), + OutputFormat::Json => serde_json::to_string(&JsonAnalysis::new(source_id, analysis)), + } +} + +fn render_human(source_id: &SourceId, source: &str, analysis: &Analysis) -> String { + use std::fmt::Write as _; + + let mut rendered = String::new(); + let handler = NarratableReportHandler::new().without_cause_chain(); + for finding in &analysis.findings { + let diagnostic = FindingDiagnostic::new(source_id, source, finding); + handler + .render_report(&mut rendered, &diagnostic) + .expect("writing a diagnostic to a String cannot fail"); + } + let summary = analysis.summary(); + let band = summary + .confidence_band + .map_or("none", john_slop::ConfidenceBand::as_str); + writeln!( + rendered, + "{}: confidence {} ({band}); {} finding(s): {} advice, {} warning, {} error", + source_id, + summary.confidence_score, + summary.findings.total(), + summary.findings.advice, + summary.findings.warnings, + summary.findings.errors, + ) + .expect("writing a summary to a String cannot fail"); + rendered +} + +fn render_concise(source_id: &SourceId, analysis: &Analysis) -> String { + use std::fmt::Write as _; + + let mut rendered = String::new(); + for finding in &analysis.findings { + writeln!( + rendered, + "{}:{}:{}: {}[{}]: {}", + source_id, + finding.byte_span.start, + finding.byte_span.end, + finding.severity, + finding.rule_id, + finding.message, + ) + .expect("writing a finding to a String cannot fail"); + } + let summary = analysis.summary(); + let band = summary + .confidence_band + .map_or("none", john_slop::ConfidenceBand::as_str); + writeln!( + rendered, + "{}: summary: confidence={} band={band} advice={} warnings={} errors={} total={}", + source_id, + summary.confidence_score, + summary.findings.advice, + summary.findings.warnings, + summary.findings.errors, + summary.findings.total(), + ) + .expect("writing a summary to a String cannot fail"); + rendered +} + +#[derive(Serialize)] +struct JsonAnalysis<'a> { + schema_version: u8, + kind: &'static str, + source: String, + summary: JsonSummary, + findings: Vec>, +} + +impl<'a> JsonAnalysis<'a> { + fn new(source_id: &SourceId, analysis: &'a Analysis) -> Self { + let summary = analysis.summary(); + Self { + schema_version: 1, + kind: "analysis", + source: source_id.to_string(), + summary: JsonSummary { + confidence_score: summary.confidence_score, + confidence_band: summary.confidence_band, + advice: summary.findings.advice, + warnings: summary.findings.warnings, + errors: summary.findings.errors, + total: summary.findings.total(), + }, + findings: analysis.findings.iter().map(JsonFinding::new).collect(), + } + } +} + +#[derive(Serialize)] +struct JsonSummary { + confidence_score: u8, + confidence_band: Option, + advice: usize, + warnings: usize, + errors: usize, + total: usize, +} + +#[derive(Serialize)] +struct JsonFinding<'a> { + rule_id: &'a str, + category: john_slop::Category, + severity: john_slop::FindingSeverity, + message: &'a str, + help: Option<&'a str>, + byte_span: JsonSpan, + matched_text: &'a str, + weight: f64, + fix: Option>, +} + +impl<'a> JsonFinding<'a> { + fn new(finding: &'a Finding) -> Self { + Self { + rule_id: finding.rule_id.as_str(), + category: finding.category, + severity: finding.severity, + message: &finding.message, + help: finding.help.as_deref(), + byte_span: JsonSpan { + start: finding.byte_span.start, + end: finding.byte_span.end, + }, + matched_text: &finding.matched_text, + weight: finding.weight, + fix: finding.fix.as_ref().map(|fix| JsonFix { + byte_span: JsonSpan { + start: fix.byte_span.start, + end: fix.byte_span.end, + }, + replacement: &fix.replacement, + }), + } + } +} + +#[derive(Serialize)] +struct JsonFix<'a> { + byte_span: JsonSpan, + replacement: &'a str, +} + +#[derive(Clone, Copy, Serialize)] +struct JsonSpan { + start: usize, + end: usize, +} + +#[cfg(test)] +mod tests { + use john_slop::{AnalysisContext, Config, Detector}; + + use super::*; + + fn analysis() -> (String, Analysis) { + let source = "préface—suffix".to_owned(); + let analysis = Detector::new(&Config::embedded()) + .unwrap() + .analyze_with(&source, &AnalysisContext::for_path("article.md")); + (source, analysis) + } + + #[test] + fn human_output_has_source_excerpt_help_and_plain_summary() { + let (source, analysis) = analysis(); + let output = render_analysis( + OutputFormat::Human, + &SourceId::File("article.md".into()), + &source, + &analysis, + ) + .unwrap(); + + assert!(output.contains("article.md")); + assert!(output.contains("préface—suffix")); + assert!(output.contains("diagnostic help:")); + assert!(output.contains("confidence")); + assert!(!output.contains('\u{1b}')); + } + + #[test] + fn json_output_is_one_versioned_machine_record() { + let (source, analysis) = analysis(); + let output = render_analysis( + OutputFormat::Json, + &SourceId::File("article.md".into()), + &source, + &analysis, + ) + .unwrap(); + let value: serde_json::Value = serde_json::from_str(&output).unwrap(); + + assert_eq!(value["schema_version"], 1); + assert_eq!(value["kind"], "analysis"); + assert_eq!(value["source"], "article.md"); + assert_eq!(value["findings"][0]["byte_span"]["start"], 8); + assert!(!output.contains('\u{1b}')); + assert!(!output.contains('\n')); + } +} diff --git a/src/model.rs b/src/model.rs index b0ec056..93c9322 100644 --- a/src/model.rs +++ b/src/model.rs @@ -45,6 +45,24 @@ pub enum Category { SourceCode, } +impl Category { + /// Return the stable kebab-case presentation name. + pub const fn as_str(self) -> &'static str { + match self { + Self::Typography => "typography", + Self::Style => "style", + Self::PromptLeakage => "prompt-leakage", + Self::SourceCode => "source-code", + } + } +} + +impl fmt::Display for Category { + fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { + formatter.write_str(self.as_str()) + } +} + /// Review severity attached to an individual configured finding. #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)] #[serde(rename_all = "lowercase")] @@ -93,7 +111,8 @@ impl Confidence { } /// Named interpretation of a non-empty analysis score. -#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)] +#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)] +#[serde(rename_all = "kebab-case")] pub enum ConfidenceBand { /// Evidence exists but remains below the configured low threshold. BelowThreshold, diff --git a/tasks.md b/tasks.md index bfd25e4..01049c3 100644 --- a/tasks.md +++ b/tasks.md @@ -144,7 +144,7 @@ formula are pinned by tests. while retaining every contributing diagnostic. - [x] Build detector CLI inputs for file, directory, and stdin (`--stdin-filename` for language/path scoping); add ignore and maximum-size controls. -- [ ] Add human, concise, and versioned JSON output modes. Ensure JSON and stdout +- [x] Add human, concise, and versioned JSON output modes. Ensure JSON and stdout diagnostics never contain logs or ANSI escapes. - [ ] Implement documented exit codes: `0` below fail threshold, `1` at/above it, `2` for usage/configuration/I/O failure. Add `--fail-level`. diff --git a/tests/snapshots/cli__help_is_successful_and_names_the_command.snap b/tests/snapshots/cli__help_is_successful_and_names_the_command.snap index 4add280..1b30dfc 100644 --- a/tests/snapshots/cli__help_is_successful_and_names_the_command.snap +++ b/tests/snapshots/cli__help_is_successful_and_names_the_command.snap @@ -38,6 +38,8 @@ Options: Virtual filename used only for standard-input language and path scoping --ignore Skip source paths matching a glob; may be supplied more than once + --output + Select human, concise, or versioned JSON output [default: human] --fail-confidence Return exit code 1 when a document reaches this evidence-confidence score [default: 100] -h, --help