secunit_core/

reports.rs

//! Report data assembly: the structured JSON behind `secunit report data`.
//!
//! Aggregates per-control coverage, sealed-run activity, and the risk
//! register over one reporting window (week, month, quarter, or year) into
//! a [`ReportData`] payload. The `report` skill renders this to prose —
//! the binary never composes the report itself, and this module never
//! captures or mutates anything.

use std::path::Path;

use chrono::{DateTime, NaiveDate, Utc};
use serde::{Deserialize, Serialize};

use crate::evidence::manifest::RunOutcome;
use crate::model::{Cadence, LoadedRegistry, RunStatus};
use crate::registry::coverage::{self, PeriodCoverage, PeriodStatus};
use crate::registry::period;
use crate::registry::resolver;
use crate::risks::{self, EventData, RiskState, Severity, Status};

// ---------- payload ---------------------------------------------------------

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReportData {
    pub schema_version: u32,
    /// `org.name` from `_config.yaml`, when set.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub org: Option<String>,
    pub period: ReportPeriod,
    /// The pinned "today" the assembly ran under — separates `Open` from
    /// `Gap` periods and drives `past_sla` / `overdue`.
    pub generated_on: NaiveDate,
    pub controls: Vec<ControlActivity>,
    pub totals: Totals,
    /// Sealed manifests that exist but could not be read or parsed. The
    /// report proceeds without them, but a non-empty list means run
    /// counts and period statuses above understate the evidence (a
    /// period may read Gap only because its manifest is unreadable) —
    /// the skill must surface these, and the operator must investigate:
    /// an altered manifest is an integrity event.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub manifest_errors: Vec<ManifestError>,
    /// Controls past due and past their cadence grace window as of
    /// `generated_on`, per the same resolver `secunit due` uses: a due
    /// date that passed without a completed run holds until satisfied or
    /// skipped, so a missed control stays here until it runs. Never-run
    /// controls have no cached due date and appear under `upcoming`;
    /// historical misses beyond the latest one surface as `Gap` rows in
    /// `controls[].periods`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub overdue: Vec<OverdueControl>,
    pub risks: RiskSummary,
    /// Controls due by `period.horizon` that are not overdue, per the
    /// same resolver `secunit due` uses. Includes a held due date still
    /// inside its grace window — due now, not yet overdue.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub upcoming: Vec<UpcomingControl>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ReportPeriod {
    /// The selector as given: `2026-W30`, `2026-07`, `2026-q3`, or `2026`.
    pub label: String,
    /// The window's own cadence — what one "period" means here.
    pub cadence: Cadence,
    pub start: NaiveDate,
    pub end: NaiveDate,
    /// The through-date `upcoming` considers: the end of the calendar
    /// period after the window, floored at the period containing
    /// `generated_on` so late-assembled reports still look forward from
    /// now. Cite this when rendering an "Upcoming" section.
    pub horizon: NaiveDate,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ControlActivity {
    pub id: String,
    pub title: String,
    pub owner: String,
    pub cadence: Cadence,
    /// Coverage rows for every period of this control's cadence touching
    /// the window (a weekly report window sits inside one quarterly
    /// period — that period appears here with its current status).
    pub periods: Vec<PeriodCoverage>,
    pub counts: PeriodCounts,
    /// Sealed runs claiming a period in the window or completed inside it.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub runs: Vec<RunSummary>,
}

#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
pub struct PeriodCounts {
    pub satisfied: usize,
    /// Satisfied, but the run sealed after the period ended.
    pub late: usize,
    pub failed: usize,
    pub gaps: usize,
    pub open: usize,
    pub skipped: usize,
    pub future: usize,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RunSummary {
    pub run_id: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub period_id: Option<String>,
    pub completed_at: DateTime<Utc>,
    pub status: RunOutcome,
    pub draft_risks: usize,
    pub draft_issues: usize,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub external_links: Vec<serde_json::Value>,
    /// Run dir relative to the secunit root.
    pub path: String,
}

#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize)]
pub struct Totals {
    pub controls: usize,
    /// Sum of `controls[].runs` lengths — which include runs merely
    /// *touching* the window (a quarterly run whose period surrounds a
    /// reported week, a catch-up run sealed inside it). Not "runs
    /// performed this window": the same surrounding-period run appears
    /// in every finer-cadence report it overlaps, and regenerating an
    /// old window after later runs seal can raise this number. Render it
    /// as "related runs", never as "runs this <period>".
    pub runs: usize,
    pub satisfied: usize,
    pub late: usize,
    pub failed: usize,
    pub gaps: usize,
    pub open: usize,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OverdueControl {
    pub id: String,
    pub title: String,
    pub owner: String,
    pub next_due: NaiveDate,
    pub days_overdue: i64,
    pub last_status: RunStatus,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct UpcomingControl {
    pub id: String,
    pub title: String,
    pub owner: String,
    pub cadence: Cadence,
    pub next_due: NaiveDate,
}

#[derive(Debug, Clone, Default, Serialize, Deserialize)]
pub struct RiskSummary {
    /// Risks currently open / in-progress, most severe first.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub open: Vec<OpenRisk>,
    /// Risks created (an `opened` event) inside the window.
    pub opened_in_period: usize,
    /// Risks reopened inside the window. Counted separately from
    /// `opened_in_period` so a reopen never reads as "no new risk".
    pub reopened_in_period: usize,
    /// Risks that closed inside the window and are still closed at the
    /// window's end. Per-risk, not per-event: close→reopen→close churn
    /// counts once, and a close undone by a reopen counts zero.
    pub closed_in_period: usize,
    /// Open risks whose SLA due date has passed `generated_on`.
    pub past_sla: usize,
    /// Accepted exceptions whose expiry (or, lacking one, original SLA
    /// date — matching `secunit risks list --past-sla`) has passed. Not
    /// "open", but the pass leadership granted has run out: the report
    /// must surface them for re-attestation or remediation.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub lapsed_exceptions: Vec<LapsedException>,
    /// Risk logs that could not be read or failed chain validation. The
    /// report proceeds without them, but a non-empty list means every
    /// count above understates the register — the skill must surface
    /// these verbatim, and the operator must investigate before trusting
    /// the risk section (a broken chain means evidence was altered).
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub register_errors: Vec<RegisterError>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RegisterError {
    pub risk_id: String,
    pub error: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LapsedException {
    pub risk_id: String,
    pub title: String,
    pub severity: Severity,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub owner: Option<String>,
    pub expired_on: NaiveDate,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ManifestError {
    pub control_id: String,
    /// Run dir relative to the secunit root.
    pub path: String,
    pub error: String,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct OpenRisk {
    pub risk_id: String,
    pub title: String,
    pub severity: Severity,
    pub status: Status,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub owner: Option<String>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub due_at: Option<NaiveDate>,
    pub past_sla: bool,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub source_control: Option<String>,
}

// ---------- assembly --------------------------------------------------------

/// Assemble the report payload for `[start, end]`, labelled `label`.
///
/// `window_cadence` is the cadence of the reporting window itself (weekly
/// report → `Weekly`) and anchors the `upcoming` horizon to the next
/// calendar period. `today` separates open from gap periods and anchors
/// SLA/overdue math — pin it (`--today`) for deterministic output.
pub fn assemble(
    reg: &LoadedRegistry,
    label: &str,
    window_cadence: Cadence,
    start: NaiveDate,
    end: NaiveDate,
    today: NaiveDate,
) -> anyhow::Result<ReportData> {
    let mut controls: Vec<ControlActivity> = Vec::new();
    let mut totals = Totals::default();

    // One walk of the whole evidence tree: coverage and the run summaries
    // below consume the same sealed manifests, bucketed per control. The
    // walk's skipped-manifest list goes into the payload — a corrupt
    // manifest must not silently read as a gap.
    let walk = coverage::sealed_runs_by_control(&reg.root)?;
    let mut runs_by_control = walk.runs;
    let manifest_errors: Vec<ManifestError> = walk
        .errors
        .into_iter()
        .map(|e| ManifestError {
            control_id: e.control_id,
            path: e
                .path
                .strip_prefix(&reg.root)
                .unwrap_or(&e.path)
                .to_string_lossy()
                .into_owned(),
            error: e.error,
        })
        .collect();

    for control in reg.controls.values() {
        let sealed = runs_by_control.remove(&control.id).unwrap_or_default();
        let cov = if matches!(control.cadence, Cadence::Continuous) {
            None
        } else {
            Some(coverage::coverage_over_runs(
                reg,
                &control.id,
                &sealed,
                start,
                end,
                today,
            )?)
        };
        let periods = cov.map(|c| c.periods).unwrap_or_default();
        let runs = runs_in_window(&reg.root, &sealed, control.cadence, &periods, start, end);

        // A control with nothing due and nothing run this window carries
        // no signal for the period — leave it out of the payload.
        if periods.is_empty() && runs.is_empty() {
            continue;
        }

        let mut counts = PeriodCounts::default();
        for p in &periods {
            match p.status {
                PeriodStatus::Satisfied => {
                    counts.satisfied += 1;
                    if p.late {
                        counts.late += 1;
                    }
                }
                PeriodStatus::Failed => counts.failed += 1,
                PeriodStatus::Gap => counts.gaps += 1,
                PeriodStatus::Open => counts.open += 1,
                PeriodStatus::Skipped => counts.skipped += 1,
                PeriodStatus::Future => counts.future += 1,
            }
        }
        totals.controls += 1;
        totals.runs += runs.len();
        totals.satisfied += counts.satisfied;
        totals.late += counts.late;
        totals.failed += counts.failed;
        totals.gaps += counts.gaps;
        totals.open += counts.open;

        controls.push(ControlActivity {
            id: control.id.clone(),
            title: control.title.clone(),
            owner: control.owner.clone(),
            cadence: control.cadence,
            periods,
            counts,
            runs,
        });
    }

    // One resolver pass; overdue and upcoming partition the same rows.
    let due_rows = resolver::due_rows(reg, today);
    let horizon = upcoming_horizon(window_cadence, start, end, today);
    let overdue = overdue_controls(reg, &due_rows, today);
    let upcoming = upcoming_controls(reg, &due_rows, horizon);
    let risks = risk_summary(&reg.root, start, end, today)?;

    Ok(ReportData {
        schema_version: crate::SCHEMA_VERSION,
        org: reg.config.org.as_ref().and_then(|o| o.name.clone()),
        period: ReportPeriod {
            label: label.to_string(),
            cadence: window_cadence,
            start,
            end,
            horizon,
        },
        generated_on: today,
        controls,
        totals,
        manifest_errors,
        overdue,
        risks,
        upcoming,
    })
}

/// The window's slice of already-walked sealed runs: a run belongs to
/// the window when it was sealed inside it (catch-up runs claiming a
/// prior period, and runs whose period id predates a cadence change,
/// must not vanish from every report) or when its claimed period touches
/// it. Pure filter — the walk happened once in `assemble`.
fn runs_in_window(
    root: &Path,
    sealed: &[coverage::SealedRun],
    cadence: Cadence,
    periods: &[PeriodCoverage],
    start: NaiveDate,
    end: NaiveDate,
) -> Vec<RunSummary> {
    let mut out: Vec<RunSummary> = Vec::new();
    for run in sealed {
        let manifest = &run.manifest;
        let completed_in_window = {
            let d = manifest.completed_at.date_naive();
            d >= start && d <= end
        };
        let in_window = completed_in_window
            || match &manifest.period_id {
                Some(pid) => {
                    periods.iter().any(|p| &p.period_id == pid)
                        || period::bounds(cadence, pid)
                            .is_some_and(|(ps, pe)| ps <= end && pe >= start)
                }
                None => false,
            };
        if !in_window {
            continue;
        }
        let rel = run
            .path
            .strip_prefix(root)
            .unwrap_or(&run.path)
            .to_string_lossy()
            .into_owned();
        out.push(RunSummary {
            run_id: manifest.run_id.clone(),
            period_id: manifest.period_id.clone(),
            completed_at: manifest.completed_at,
            status: manifest.status,
            draft_risks: manifest.draft_risks.len(),
            draft_issues: manifest.draft_issues.len(),
            external_links: manifest.external_links.clone(),
            path: rel,
        });
    }
    out.sort_by_key(|r| r.completed_at);
    out
}

/// Overdue per the resolver — the same due dates, schedule overrides,
/// never-run handling, and per-cadence grace `secunit due` applies, so the
/// report can never contradict it.
fn overdue_controls(
    reg: &LoadedRegistry,
    due_rows: &[resolver::DueRow],
    today: NaiveDate,
) -> Vec<OverdueControl> {
    let mut out: Vec<OverdueControl> = Vec::new();
    for row in due_rows {
        if !row.overdue {
            continue;
        }
        let Some(next_due) = row.next_due else {
            continue;
        };
        let Some(control) = reg.controls.get(&row.control_id) else {
            continue;
        };
        let last_status = reg
            .state
            .controls
            .get(&row.control_id)
            .map(|e| e.last_status)
            .unwrap_or(RunStatus::NeverRun);
        out.push(OverdueControl {
            id: control.id.clone(),
            title: control.title.clone(),
            owner: control.owner.clone(),
            next_due,
            days_overdue: (today - next_due).num_days(),
            last_status,
        });
    }
    out.sort_by_key(|o| std::cmp::Reverse(o.days_overdue));
    out
}

/// The `upcoming` through-date: the end of the calendar period after the
/// window, floored at the period containing `today` — a report assembled
/// long after its window still looks forward from now instead of at an
/// interval that already ended.
fn upcoming_horizon(
    window_cadence: Cadence,
    start: NaiveDate,
    end: NaiveDate,
    today: NaiveDate,
) -> NaiveDate {
    let anchor = (end + chrono::Duration::days(1)).max(today);
    period::derive(window_cadence, anchor)
        .and_then(|pid| period::bounds(window_cadence, &pid))
        .map(|(_, pe)| pe)
        // Continuous has no periods; fall back to one window-length.
        .unwrap_or(anchor + chrono::Duration::days((end - start).num_days()))
}

/// Controls due by `horizon`, resolver-computed like `overdue_controls`.
/// Every due row lands in exactly one list: overdue rows there, all
/// other in-horizon rows here — including a held due date still inside
/// its grace window (due, not yet overdue).
fn upcoming_controls(
    reg: &LoadedRegistry,
    due_rows: &[resolver::DueRow],
    horizon: NaiveDate,
) -> Vec<UpcomingControl> {
    let mut out: Vec<UpcomingControl> = Vec::new();
    for row in due_rows {
        if row.overdue {
            continue;
        }
        let Some(next_due) = row.next_due else {
            continue;
        };
        if next_due > horizon {
            continue;
        }
        let Some(control) = reg.controls.get(&row.control_id) else {
            continue;
        };
        out.push(UpcomingControl {
            id: control.id.clone(),
            title: control.title.clone(),
            owner: control.owner.clone(),
            cadence: control.cadence,
            next_due,
        });
    }
    out.sort_by(|a, b| a.next_due.cmp(&b.next_due).then(a.id.cmp(&b.id)));
    out
}

/// Fold every risk log under `risks/` into the report's register view:
/// currently-open risks plus opened/reopened/closed counts inside the
/// window. A corrupt log doesn't abort the report — that would take the
/// reporting cadence itself into gap until the append-only log is
/// restored — but it is never silent either: the broken risk lands in
/// `register_errors`, in-band where the skill and the reader see it.
fn risk_summary(
    root: &Path,
    start: NaiveDate,
    end: NaiveDate,
    today: NaiveDate,
) -> anyhow::Result<RiskSummary> {
    let mut summary = RiskSummary::default();
    // The store's shared lenient load — the same degradation rule
    // `risks list` and the GUI use. Make paths store-relative: the skill
    // headlines these strings and may publish the report as a tracker
    // issue, so the operator's absolute filesystem layout must not
    // travel with them.
    let register = risks::load_register(root)?;
    summary.register_errors = register
        .errors
        .into_iter()
        .map(|(risk_id, error)| RegisterError {
            risk_id,
            error: error.replace(&format!("{}/", root.display()), ""),
        })
        .collect();
    for (risk_id, events) in register.risks {
        // Count per risk, not per event: a close that a later in-window
        // reopen undoes must not read as a closure, and churn must not
        // double-count. `closed` therefore requires both an in-window
        // closing event and a closed status when the window ends.
        let mut opened = false;
        let mut reopened = false;
        let mut closing_event = false;
        for ev in &events {
            let d = ev.ts.date_naive();
            if d < start || d > end {
                continue;
            }
            match &ev.data {
                EventData::Opened { .. } => opened = true,
                EventData::Reopened { .. } => reopened = true,
                EventData::Remediated { .. } | EventData::ExceptionDocumented { .. } => {
                    closing_event = true
                }
                EventData::StatusChanged { to, .. } => {
                    if to.is_closed() {
                        closing_event = true;
                    } else if matches!(to, Status::Reopened) {
                        reopened = true;
                    }
                }
                _ => {}
            }
        }
        if opened {
            summary.opened_in_period += 1;
        }
        if reopened {
            summary.reopened_in_period += 1;
        }
        if closing_event {
            let closed_at_end = risks::fold_at(&events, end).is_some_and(|s| s.status.is_closed());
            if closed_at_end {
                summary.closed_in_period += 1;
            }
        }

        let state: RiskState = risks::fold(&events);
        if state.status.is_open() {
            let past_sla = state.due_at.is_some_and(|d| d < today);
            if past_sla {
                summary.past_sla += 1;
            }
            summary.open.push(OpenRisk {
                risk_id,
                title: state.title.clone(),
                severity: state.severity,
                status: state.status,
                owner: state.owner.clone(),
                due_at: state.due_at,
                past_sla,
                source_control: state.source_control().map(str::to_string),
            });
        } else if matches!(state.status, Status::AcceptedException) {
            // An exception's pass can run out; expiry first, else the
            // original SLA date — the same trigger `risks list --past-sla`
            // uses — so the report and the CLI agree on lapsed exceptions.
            let expired_on = state.exception_expires_at.or(state.due_at);
            if let Some(expired_on) = expired_on.filter(|d| *d < today) {
                summary.lapsed_exceptions.push(LapsedException {
                    risk_id,
                    title: state.title.clone(),
                    severity: state.severity,
                    owner: state.owner.clone(),
                    expired_on,
                });
            }
        }
    }
    summary
        .open
        .sort_by(|a, b| a.severity.cmp(&b.severity).then(a.risk_id.cmp(&b.risk_id)));
    Ok(summary)
}