tga 2.4.0

Developer productivity analytics — git commit collection, classification, and reporting
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87

//! JSON formatter — writes `report.json` (pretty-printed).

use std::path::{Path, PathBuf};

use tracing::debug;

use crate::report::errors::Result;
use crate::report::models::ReportData;

/// Filename for the JSON output.
pub const REPORT_JSON: &str = "report.json";

/// Filename for the velocity summary JSON.
pub const VELOCITY_JSON: &str = "velocity_summary.json";

/// Filename for the quality summary JSON.
pub const QUALITY_JSON: &str = "quality_summary.json";

/// Filename for the DORA summary JSON.
pub const DORA_JSON: &str = "dora_summary.json";

/// Write `velocity_summary.json`.
///
/// Why: dashboards consume velocity metrics as structured JSON; we keep this
/// file separate from the omnibus `report.json` so it can be polled cheaply.
/// What: serializes [`crate::report::models::VelocitySummary`] (or `null`).
/// Test: invoke after aggregation, parse the resulting JSON, assert
/// `pr_count` matches the seeded PR rows.
///
/// # Errors
/// - [`crate::report::ReportError::Io`] / [`crate::report::ReportError::Json`] on failure.
pub fn write_velocity_json(data: &ReportData, output_dir: &Path) -> Result<PathBuf> {
    let path = output_dir.join(VELOCITY_JSON);
    let file = std::fs::File::create(&path)?;
    serde_json::to_writer_pretty(file, &data.velocity)?;
    debug!(path = %path.display(), "wrote velocity_summary.json");
    Ok(path)
}

/// Write `quality_summary.json`.
///
/// Why: quality scoring is consumed by retro tooling separately from the
/// activity dashboard, so it gets a dedicated file.
/// What: serializes [`crate::report::models::QualitySummary`] (or `null`).
/// Test: assert `quality_score` is in `[0, 1]` after writing.
///
/// # Errors
/// - [`crate::report::ReportError::Io`] / [`crate::report::ReportError::Json`] on failure.
pub fn write_quality_json(data: &ReportData, output_dir: &Path) -> Result<PathBuf> {
    let path = output_dir.join(QUALITY_JSON);
    let file = std::fs::File::create(&path)?;
    serde_json::to_writer_pretty(file, &data.quality)?;
    debug!(path = %path.display(), "wrote quality_summary.json");
    Ok(path)
}

/// Write `dora_summary.json`.
///
/// Why: keeps the DORA payload available even when the `csv` output format
/// is disabled.
/// What: serializes [`crate::report::models::DoraMetrics`] (or `null`).
/// Test: parse the resulting JSON, assert `performance_level` is one of
/// `"elite" | "high" | "medium" | "low"`.
///
/// # Errors
/// - [`crate::report::ReportError::Io`] / [`crate::report::ReportError::Json`] on failure.
pub fn write_dora_json(data: &ReportData, output_dir: &Path) -> Result<PathBuf> {
    let path = output_dir.join(DORA_JSON);
    let file = std::fs::File::create(&path)?;
    serde_json::to_writer_pretty(file, &data.dora)?;
    debug!(path = %path.display(), "wrote dora_summary.json");
    Ok(path)
}

/// Serialize [`ReportData`] as pretty JSON into `<output_dir>/report.json`.
///
/// # Errors
///
/// - [`crate::report::ReportError::Io`] on write failure.
/// - [`crate::report::ReportError::Json`] on serialization failure.
pub fn write_json(data: &ReportData, output_dir: &Path) -> Result<PathBuf> {
    let path = output_dir.join(REPORT_JSON);
    let file = std::fs::File::create(&path)?;
    serde_json::to_writer_pretty(file, data)?;
    debug!(path = %path.display(), "wrote report.json");
    Ok(path)
}