feat: add structured detector output modes

This commit is contained in:
Dandaedre 2026-09-29 15:57:40 +02:00
parent c9b280e9fe
commit cf4f0be12d
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
8 changed files with 317 additions and 12 deletions

26
Cargo.lock generated
View File

@ -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"

View File

@ -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"

View File

@ -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.

View File

@ -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<String>,
/// 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<bool> {
});
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<bool> {
}
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;
}

237
src/bin/john-slop/output.rs Normal file
View File

@ -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<String, serde_json::Error> {
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<JsonFinding<'a>>,
}
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<john_slop::ConfidenceBand>,
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<JsonFix<'a>>,
}
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'));
}
}

View File

@ -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,

View File

@ -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`.

View File

@ -38,6 +38,8 @@ Options:
Virtual filename used only for standard-input language and path scoping
--ignore <GLOB>
Skip source paths matching a glob; may be supplied more than once
--output <human|concise|json>
Select human, concise, or versioned JSON output [default: human]
--fail-confidence <FAIL_CONFIDENCE>
Return exit code 1 when a document reaches this evidence-confidence score [default: 100]
-h, --help