agentsec_core/output/

markdown.rs

//! Markdown renderers.
//!
//! Two entry points:
//!
//! - [`render`] — full scan report from a [`ScanOutcome`].
//! - [`render_diff`] — standalone diff section from a
//!   [`crate::scan::diff::DiffReport`], used by `agentsec diff` and the
//!   `scan_diff` MCP tool.
//!
//! ## `render` output sections (always in this order)
//!
//! 1. `# AgentSec scan — <RFC 3339 UTC>` header + total path count.
//! 2. `## Inventory` table with one row per [`crate::scan::inventory::PathEntry`].
//! 3. `## Diff vs previous snapshot` — `_no previous snapshot — this is the
//!    baseline._` on first run, `_no changes._` when the diff is empty,
//!    otherwise three subsections (`### Added`, `### Modified`,
//!    `### Removed`).
//! 4. Footer line with the absolute snapshot path.
//!
//! Pure functions: no I/O, no allocation beyond the output string.

use crate::scan::unknown::{UnknownVerdict, UnknownVerdictKind};
use crate::scan::{ScanOutcome, ScanReport, diff::DiffReport};
use std::fmt::Write;

/// Render `outcome` as a Markdown report (see module docs §`render` output
/// sections for the schema).
pub fn render(outcome: &ScanOutcome) -> String {
    let mut s = String::new();
    write_header(&mut s, &outcome.report);
    write_inventory(&mut s, &outcome.report);
    write_diff(&mut s, outcome);
    write_footer(&mut s, outcome);
    s
}

fn write_header(s: &mut String, report: &ScanReport) {
    let _ = writeln!(s, "# AgentSec scan — {}", report.scanned_at.to_rfc3339());
    let _ = writeln!(s);
    let _ = writeln!(s, "Total paths inventoried: **{}**", report.paths.len());
    let _ = writeln!(s);
}

fn write_inventory(s: &mut String, report: &ScanReport) {
    let _ = writeln!(s, "## Inventory");
    let _ = writeln!(s);
    if report.paths.is_empty() {
        let _ = writeln!(s, "_no targets present._");
        let _ = writeln!(s);
        return;
    }
    let _ = writeln!(s, "| category | path | size | sha256 |");
    let _ = writeln!(s, "|---|---|---|---|");
    for p in &report.paths {
        let _ = writeln!(
            s,
            "| {} | `{}` | {} | `{}` |",
            p.category,
            p.path.display(),
            p.size,
            &p.sha256[..16]
        );
    }
    let _ = writeln!(s);
}

fn write_diff(s: &mut String, outcome: &ScanOutcome) {
    let Some(diff) = &outcome.diff else {
        let _ = writeln!(s, "## Diff vs previous snapshot");
        let _ = writeln!(s);
        let _ = writeln!(s, "_no previous snapshot — this is the baseline._");
        let _ = writeln!(s);
        return;
    };
    let _ = writeln!(s, "## Diff vs previous snapshot");
    let _ = writeln!(s);
    if diff.is_empty() {
        let _ = writeln!(s, "_no changes._");
        let _ = writeln!(s);
        return;
    }
    if !diff.added.is_empty() {
        let _ = writeln!(s, "### Added ({})", diff.added.len());
        for e in &diff.added {
            let _ = writeln!(s, "- `{}` ({} bytes)", e.path.display(), e.size);
        }
        let _ = writeln!(s);
    }
    if !diff.modified.is_empty() {
        let _ = writeln!(s, "### Modified ({})", diff.modified.len());
        for c in &diff.modified {
            let _ = writeln!(
                s,
                "- `{}` ({} → {} bytes, sha256 `{}` → `{}`)",
                c.path.display(),
                c.prev_size,
                c.curr_size,
                &c.prev_sha256[..8],
                &c.curr_sha256[..8]
            );
        }
        let _ = writeln!(s);
    }
    if !diff.removed.is_empty() {
        let _ = writeln!(s, "### Removed ({})", diff.removed.len());
        for e in &diff.removed {
            let _ = writeln!(s, "- `{}`", e.path.display());
        }
        let _ = writeln!(s);
    }
}

/// Render a standalone diff report as Markdown.
///
/// Schema:
///
/// - `# AgentSec diff vs <baseline-path-or-"latest snapshot">` — header.
/// - If the diff is empty, a single `_no changes._` line and nothing else.
/// - Otherwise the three `### Added` / `### Modified` / `### Removed`
///   subsections, each omitted when its vector is empty.
///
/// Pass `baseline_hint` as `Some("/path/to/snapshot")` to put the
/// snapshot path in the header, or `None` for the generic phrasing.
pub fn render_diff(diff: &DiffReport, baseline_hint: Option<&str>) -> String {
    let mut s = String::new();
    let header = match baseline_hint {
        Some(p) => format!("# AgentSec diff vs `{p}`\n\n"),
        None => "# AgentSec diff vs latest snapshot\n\n".to_string(),
    };
    s.push_str(&header);
    if diff.is_empty() {
        let _ = writeln!(s, "_no changes._");
        return s;
    }
    if !diff.added.is_empty() {
        let _ = writeln!(s, "### Added ({})", diff.added.len());
        for e in &diff.added {
            let _ = writeln!(s, "- `{}` ({} bytes)", e.path.display(), e.size);
        }
        let _ = writeln!(s);
    }
    if !diff.modified.is_empty() {
        let _ = writeln!(s, "### Modified ({})", diff.modified.len());
        for c in &diff.modified {
            let _ = writeln!(
                s,
                "- `{}` ({} → {} bytes, sha256 `{}` → `{}`)",
                c.path.display(),
                c.prev_size,
                c.curr_size,
                &c.prev_sha256[..8],
                &c.curr_sha256[..8]
            );
        }
        let _ = writeln!(s);
    }
    if !diff.removed.is_empty() {
        let _ = writeln!(s, "### Removed ({})", diff.removed.len());
        for e in &diff.removed {
            let _ = writeln!(s, "- `{}`", e.path.display());
        }
        let _ = writeln!(s);
    }
    s
}

/// Render BlackList classify verdicts as Markdown.
///
/// Empty input ⇒ a single `_no MCP servers found in .mcp.json / .claude.json._`
/// notice. Otherwise three subsections (`### Known-good`, `### Typosquat
/// candidates`, `### Unknown`) in that order. Each subsection is omitted
/// when its bucket is empty.
pub fn render_blacklist(verdicts: &[UnknownVerdict], registry_size: usize) -> String {
    let mut s = String::new();
    let _ = writeln!(s, "# AgentSec BlackList check");
    let _ = writeln!(s);
    let _ = writeln!(s, "Registry: {registry_size} known-good entries.");
    let _ = writeln!(s);
    if verdicts.is_empty() {
        let _ = writeln!(s, "_no MCP servers found in .mcp.json / .claude.json._");
        return s;
    }
    let mut good = Vec::new();
    let mut typo = Vec::new();
    let mut unk = Vec::new();
    for v in verdicts {
        match &v.verdict {
            UnknownVerdictKind::KnownGood => good.push(v),
            UnknownVerdictKind::Typosquat { .. } => typo.push(v),
            UnknownVerdictKind::Unknown => unk.push(v),
        }
    }
    if !good.is_empty() {
        let _ = writeln!(s, "### Known-good ({})", good.len());
        for v in good {
            let _ = writeln!(s, "- `{}` — {} (from `{}`)", v.name, v.reason, v.path);
        }
        let _ = writeln!(s);
    }
    if !typo.is_empty() {
        let _ = writeln!(s, "### Typosquat candidates ({})", typo.len());
        for v in typo {
            let _ = writeln!(s, "- `{}` — {} (from `{}`)", v.name, v.reason, v.path);
        }
        let _ = writeln!(s);
    }
    if !unk.is_empty() {
        let _ = writeln!(s, "### Unknown ({})", unk.len());
        for v in unk {
            let _ = writeln!(s, "- `{}` — {} (from `{}`)", v.name, v.reason, v.path);
        }
        let _ = writeln!(s);
    }
    s
}

/// Short one-line diff summary for hook stderr output.
///
/// Format: `N added, M modified, K removed` (omits zero-count terms).
/// Returns `"no changes"` for an empty diff.
///
/// # Examples
///
/// ```
/// use agentsec_core::output::markdown::diff_summary_line;
/// use agentsec_core::scan::diff::DiffReport;
///
/// let empty = DiffReport { added: vec![], modified: vec![], removed: vec![] };
/// assert_eq!(diff_summary_line(&empty), "no changes");
/// ```
pub fn diff_summary_line(diff: &DiffReport) -> String {
    if diff.is_empty() {
        return "no changes".to_string();
    }
    let mut parts = Vec::new();
    if !diff.added.is_empty() {
        parts.push(format!("{} added", diff.added.len()));
    }
    if !diff.modified.is_empty() {
        parts.push(format!("{} modified", diff.modified.len()));
    }
    if !diff.removed.is_empty() {
        parts.push(format!("{} removed", diff.removed.len()));
    }
    parts.join(", ")
}

fn write_footer(s: &mut String, outcome: &ScanOutcome) {
    let _ = writeln!(
        s,
        "_snapshot written to: `{}`_",
        outcome.snapshot_path.display()
    );
}