fallow_api/
audit_output.rs

1//! Shared audit JSON payload contracts for programmatic consumers.
2
3use fallow_config::AuditGate;
4use fallow_output::{
5    AuditCommand, CodeClimateIssue, RootEnvelopeMode, codeclimate_issues_to_value,
6};
7use fallow_types::duplicates::DuplicationReport;
8use fallow_types::envelope::{ElapsedMs, SchemaVersion, ToolVersion};
9use fallow_types::output::NextStep;
10use serde::Serialize;
11
12/// Verdict for the audit command.
13#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize)]
14#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
15#[serde(rename_all = "snake_case")]
16pub enum AuditVerdict {
17    /// No issues in changed files.
18    Pass,
19    /// Issues found, but all are warn-severity.
20    Warn,
21    /// Error-severity issues found in changed files.
22    Fail,
23}
24
25/// Per-category summary counts for the audit result.
26#[derive(Debug, Clone, Serialize)]
27#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
28pub struct AuditSummary {
29    pub dead_code_issues: usize,
30    pub dead_code_has_errors: bool,
31    pub complexity_findings: usize,
32    pub max_cyclomatic: Option<u16>,
33    pub duplication_clone_groups: usize,
34}
35
36/// New-vs-inherited issue counts for audit.
37#[derive(Debug, Default, Clone, Serialize)]
38#[cfg_attr(feature = "schema", derive(schemars::JsonSchema))]
39pub struct AuditAttribution {
40    pub gate: AuditGate,
41    pub dead_code_introduced: usize,
42    pub dead_code_inherited: usize,
43    pub complexity_introduced: usize,
44    pub complexity_inherited: usize,
45    pub duplication_introduced: usize,
46    pub duplication_inherited: usize,
47}
48
49/// Header fields shared by audit JSON and review-brief subtract sections.
50pub struct AuditJsonHeaderInput {
51    pub schema_version: SchemaVersion,
52    pub version: ToolVersion,
53    pub verdict: AuditVerdict,
54    pub changed_files_count: u32,
55    pub base_ref: String,
56    pub base_description: Option<String>,
57    pub head_sha: Option<String>,
58    pub elapsed_ms: ElapsedMs,
59    pub base_snapshot_skipped: Option<bool>,
60    pub summary: AuditSummary,
61    pub attribution: AuditAttribution,
62}
63
64/// Typed audit JSON assembly input.
65pub struct AuditJsonOutputInput<DeadCode, Duplication, Complexity> {
66    pub header: AuditJsonHeaderInput,
67    pub dead_code: Option<DeadCode>,
68    pub duplication: Option<Duplication>,
69    pub complexity: Option<Complexity>,
70    pub next_steps: Vec<NextStep>,
71}
72
73/// Typed audit SARIF assembly input.
74#[derive(Clone, Copy)]
75pub struct AuditSarifOutputInput<'a> {
76    pub dead_code: Option<&'a serde_json::Value>,
77    pub duplication: Option<&'a DuplicationReport>,
78    pub health: Option<&'a serde_json::Value>,
79}
80
81/// Typed audit CodeClimate assembly input.
82pub struct AuditCodeClimateOutputInput {
83    pub dead_code: Vec<CodeClimateIssue>,
84    pub duplication: Vec<CodeClimateIssue>,
85    pub health: Vec<CodeClimateIssue>,
86}
87
88#[derive(Serialize)]
89struct AuditHeaderOutput {
90    schema_version: SchemaVersion,
91    version: ToolVersion,
92    command: AuditCommand,
93    verdict: AuditVerdict,
94    changed_files_count: u32,
95    base_ref: String,
96    #[serde(default, skip_serializing_if = "Option::is_none")]
97    base_description: Option<String>,
98    #[serde(default, skip_serializing_if = "Option::is_none")]
99    head_sha: Option<String>,
100    elapsed_ms: ElapsedMs,
101    #[serde(default, skip_serializing_if = "Option::is_none")]
102    base_snapshot_skipped: Option<bool>,
103    summary: AuditSummary,
104    attribution: AuditAttribution,
105}
106
107fn audit_header_output(input: AuditJsonHeaderInput) -> AuditHeaderOutput {
108    AuditHeaderOutput {
109        schema_version: input.schema_version,
110        version: input.version,
111        command: AuditCommand::Audit,
112        verdict: input.verdict,
113        changed_files_count: input.changed_files_count,
114        base_ref: input.base_ref,
115        base_description: input.base_description,
116        head_sha: input.head_sha,
117        elapsed_ms: input.elapsed_ms,
118        base_snapshot_skipped: input.base_snapshot_skipped,
119        summary: input.summary,
120        attribution: input.attribution,
121    }
122}
123
124/// Build the audit header JSON object used by review brief output.
125///
126/// # Errors
127///
128/// Returns a serde error if one of the typed header fields cannot be converted
129/// to JSON.
130pub fn build_audit_header_json(
131    input: AuditJsonHeaderInput,
132) -> Result<serde_json::Value, serde_json::Error> {
133    serde_json::to_value(audit_header_output(input))
134}
135
136/// Build the audit header as an object map for composed output contracts such
137/// as review briefs.
138///
139/// # Errors
140///
141/// Returns a serde error if one of the typed header fields cannot be converted
142/// to JSON, or if the typed header unexpectedly does not serialize to an
143/// object.
144pub fn build_audit_header_map(
145    input: AuditJsonHeaderInput,
146) -> Result<serde_json::Map<String, serde_json::Value>, serde_json::Error> {
147    match build_audit_header_json(input)? {
148        serde_json::Value::Object(header) => Ok(header),
149        _ => unreachable!("AuditHeaderOutput serializes to an object"),
150    }
151}
152
153/// Serialize a typed audit JSON output envelope.
154///
155/// # Errors
156///
157/// Returns a serde error if the envelope or one of its nested payload sections
158/// cannot be converted to JSON.
159pub fn serialize_audit_json<DeadCode, Duplication, Complexity>(
160    input: AuditJsonOutputInput<DeadCode, Duplication, Complexity>,
161    mode: RootEnvelopeMode,
162    analysis_run_id: Option<&str>,
163) -> Result<serde_json::Value, serde_json::Error>
164where
165    DeadCode: Serialize,
166    Duplication: Serialize,
167    Complexity: Serialize,
168{
169    let header = audit_header_output(input.header);
170    let output = fallow_output::AuditOutput {
171        schema_version: header.schema_version,
172        version: header.version,
173        command: header.command,
174        verdict: header.verdict,
175        changed_files_count: header.changed_files_count,
176        base_ref: header.base_ref,
177        base_description: header.base_description,
178        head_sha: header.head_sha,
179        elapsed_ms: header.elapsed_ms,
180        base_snapshot_skipped: header.base_snapshot_skipped,
181        summary: header.summary,
182        attribution: header.attribution,
183        meta: None,
184        dead_code: input.dead_code,
185        duplication: input.duplication,
186        complexity: input.complexity,
187        next_steps: input.next_steps,
188    };
189    fallow_output::serialize_audit_json_output(output, mode, analysis_run_id)
190}
191
192/// Build the combined SARIF document for `fallow audit`.
193#[must_use]
194pub fn build_audit_sarif(input: AuditSarifOutputInput<'_>) -> serde_json::Value {
195    let mut all_runs = Vec::new();
196
197    if let Some(sarif) = input.dead_code {
198        extend_sarif_runs(&mut all_runs, sarif);
199    }
200
201    if let Some(duplication) = input.duplication
202        && !duplication.clone_groups.is_empty()
203    {
204        all_runs.push(build_audit_duplication_sarif_run(duplication));
205    }
206
207    if let Some(sarif) = input.health {
208        extend_sarif_runs(&mut all_runs, sarif);
209    }
210
211    serde_json::json!({
212        "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
213        "version": "2.1.0",
214        "runs": all_runs,
215    })
216}
217
218fn extend_sarif_runs(all_runs: &mut Vec<serde_json::Value>, sarif: &serde_json::Value) {
219    if let Some(runs) = sarif.get("runs").and_then(|runs| runs.as_array()) {
220        all_runs.extend(runs.iter().cloned());
221    }
222}
223
224fn build_audit_duplication_sarif_run(duplication: &DuplicationReport) -> serde_json::Value {
225    serde_json::json!({
226        "tool": {
227            "driver": {
228                "name": "fallow",
229                "version": env!("CARGO_PKG_VERSION"),
230                "informationUri": "https://github.com/fallow-rs/fallow",
231            }
232        },
233        "automationDetails": { "id": "fallow/audit/dupes" },
234        "results": duplication.clone_groups.iter().enumerate().map(|(i, group)| {
235            serde_json::json!({
236                "ruleId": "fallow/code-duplication",
237                "level": "warning",
238                "message": {
239                    "text": format!(
240                        "Clone group {} ({} lines, {} instances)",
241                        i + 1,
242                        group.line_count,
243                        group.instances.len()
244                    ),
245                },
246            })
247        }).collect::<Vec<_>>()
248    })
249}
250
251/// Build combined CodeClimate issues for `fallow audit`.
252#[must_use]
253pub fn build_audit_codeclimate_issues(input: AuditCodeClimateOutputInput) -> Vec<CodeClimateIssue> {
254    let mut all_issues = input.dead_code;
255    all_issues.extend(input.duplication);
256    all_issues.extend(input.health);
257    all_issues
258}
259
260/// Build the combined CodeClimate JSON array for `fallow audit`.
261#[must_use]
262pub fn build_audit_codeclimate(input: AuditCodeClimateOutputInput) -> serde_json::Value {
263    codeclimate_issues_to_value(&build_audit_codeclimate_issues(input))
264}
265
266#[cfg(test)]
267mod tests {
268    use super::*;
269
270    #[test]
271    fn audit_verdict_uses_snake_case_wire_names() {
272        let value = serde_json::to_value(AuditVerdict::Pass).expect("serialize verdict");
273        assert_eq!(value, serde_json::json!("pass"));
274    }
275
276    fn header_input() -> AuditJsonHeaderInput {
277        AuditJsonHeaderInput {
278            schema_version: SchemaVersion(7),
279            version: ToolVersion("0.0.0-test".to_string()),
280            verdict: AuditVerdict::Pass,
281            changed_files_count: 5,
282            base_ref: "abc123".to_string(),
283            base_description: Some("merge-base with origin/main".to_string()),
284            head_sha: Some("def456".to_string()),
285            elapsed_ms: ElapsedMs(12),
286            base_snapshot_skipped: Some(true),
287            summary: AuditSummary {
288                dead_code_issues: 0,
289                dead_code_has_errors: false,
290                complexity_findings: 0,
291                max_cyclomatic: None,
292                duplication_clone_groups: 0,
293            },
294            attribution: AuditAttribution {
295                gate: AuditGate::NewOnly,
296                ..AuditAttribution::default()
297            },
298        }
299    }
300
301    #[test]
302    fn audit_header_json_uses_typed_contract_fields() {
303        let value = build_audit_header_json(header_input()).expect("serialize audit header");
304
305        assert_eq!(value["schema_version"], 7);
306        assert_eq!(value["command"], "audit");
307        assert_eq!(value["base_description"], "merge-base with origin/main");
308        assert_eq!(value["head_sha"], "def456");
309        assert_eq!(value["base_snapshot_skipped"], true);
310    }
311
312    #[test]
313    fn audit_header_map_uses_typed_contract_fields() {
314        let header = build_audit_header_map(header_input()).expect("serialize audit header");
315
316        assert_eq!(header["schema_version"], 7);
317        assert_eq!(header["command"], "audit");
318        assert_eq!(header["base_description"], "merge-base with origin/main");
319    }
320
321    #[test]
322    fn audit_json_serializer_applies_root_kind_and_sections() {
323        let value = serialize_audit_json(
324            AuditJsonOutputInput {
325                header: header_input(),
326                dead_code: Some(serde_json::json!({"total_issues": 0})),
327                duplication: None::<serde_json::Value>,
328                complexity: None::<serde_json::Value>,
329                next_steps: Vec::new(),
330            },
331            RootEnvelopeMode::Tagged,
332            Some("run-1"),
333        )
334        .expect("serialize audit output");
335
336        assert_eq!(value["kind"], "audit");
337        assert_eq!(value["dead_code"]["total_issues"], 0);
338        assert_eq!(value["_meta"]["telemetry"]["analysis_run_id"], "run-1");
339    }
340
341    #[test]
342    fn audit_sarif_combines_runs_and_duplication_run() {
343        let duplication = DuplicationReport {
344            clone_groups: vec![fallow_types::duplicates::CloneGroup {
345                instances: vec![
346                    fallow_types::duplicates::CloneInstance {
347                        file: "src/a.ts".into(),
348                        start_line: 1,
349                        end_line: 12,
350                        start_col: 1,
351                        end_col: 1,
352                        fragment: "duplicated();".to_string(),
353                    },
354                    fallow_types::duplicates::CloneInstance {
355                        file: "src/b.ts".into(),
356                        start_line: 1,
357                        end_line: 12,
358                        start_col: 1,
359                        end_col: 1,
360                        fragment: "duplicated();".to_string(),
361                    },
362                ],
363                token_count: 40,
364                line_count: 12,
365            }],
366            ..DuplicationReport::default()
367        };
368        let dead_code = serde_json::json!({"runs": [{"automationDetails": {"id": "check"}}]});
369        let health = serde_json::json!({"runs": [{"automationDetails": {"id": "health"}}]});
370
371        let value = build_audit_sarif(AuditSarifOutputInput {
372            dead_code: Some(&dead_code),
373            duplication: Some(&duplication),
374            health: Some(&health),
375        });
376
377        assert_eq!(value["version"], "2.1.0");
378        assert_eq!(value["runs"].as_array().expect("runs").len(), 3);
379        assert_eq!(
380            value["runs"][1]["automationDetails"]["id"],
381            "fallow/audit/dupes"
382        );
383    }
384
385    #[test]
386    fn audit_codeclimate_combines_issue_sections() {
387        let issue = CodeClimateIssue {
388            kind: fallow_output::CodeClimateIssueKind::Issue,
389            check_name: "fallow/test".to_string(),
390            description: "test".to_string(),
391            severity: fallow_output::CodeClimateSeverity::Minor,
392            fingerprint: "abc".to_string(),
393            location: fallow_output::CodeClimateLocation {
394                path: "src/a.ts".to_string(),
395                lines: fallow_output::CodeClimateLines { begin: 1 },
396            },
397            categories: vec!["Bug Risk".to_string()],
398            owner: None,
399            group: None,
400        };
401
402        let value = build_audit_codeclimate(AuditCodeClimateOutputInput {
403            dead_code: vec![issue.clone()],
404            duplication: vec![issue.clone()],
405            health: vec![issue],
406        });
407
408        assert_eq!(value.as_array().expect("issues").len(), 3);
409    }
410}
fallow_api/audit_output.rs

fallow_api/
audit_output.rs
