use super::{
AnalysisResult, collect_hotspot_rows, filter_complexity, filter_interface, filter_volume,
format_rel_path, get_sorted_hotspots, star_string,
};
use crate::analysis::FunctionMetric;
use crate::scoring::Score;
use std::collections::HashMap;
use std::fmt::Write;
use std::fs;
use std::io;
use std::path::{Path, PathBuf};
pub fn generate_markdown_report(res: &AnalysisResult, root_dir: &Path) -> io::Result<PathBuf> {
let out_dir = root_dir.join("tools").join("cargo-sig");
if !out_dir.exists() {
fs::create_dir_all(&out_dir)?;
}
let report_path = out_dir.join("SIG_REPORT.md");
fs::write(&report_path, render_markdown(res, root_dir))?;
Ok(report_path)
}
#[must_use]
pub fn render_markdown(res: &AnalysisResult, root_dir: &Path) -> String {
let mut out = String::with_capacity(8192);
out.push_str("# SIG Maintainability Audit Report\n\n> Generated by [cargo-sig](https://github.com/Vicente-Alejandro/Cargo-Software-Improvement-Group-Analyzer) — Local Software Improvement Group static analysis.\n\n");
let mut ctx = MarkdownCtx { out: &mut out, res, root_dir };
ctx.render_all();
out
}
struct MetricHeader<'a> {
title: &'a str,
empty_msg: &'a str,
val_header: &'a str,
}
struct MarkdownCtx<'a> {
out: &'a mut String,
res: &'a AnalysisResult<'a>,
root_dir: &'a Path,
}
impl MarkdownCtx<'_> {
fn render_all(&mut self) {
self.render_summary();
self.render_violations();
self.render_hotspots();
self.render_architecture();
self.render_history();
}
fn render_summary(&mut self) {
self.out.push_str("## Maintainability Scorecard\n\n");
self.render_scorecard_rows();
self.render_risk_table();
}
#[rustfmt::skip]
fn render_scorecard_rows(&mut self) {
let s = self.res.score;
let d_stars = self.res.delta.map_or(String::new(), |d| format!(" `[{}]`", crate::history::format_delta_stars(d.delta_stars)));
let d_code = self.res.delta.map_or(String::new(), |d| format!(" `[{}]`", crate::history::format_delta_stars(d.delta_code_stars)));
let d_vol = self.res.delta.map_or(String::new(), |d| format!(" `[{}]`", crate::history::format_delta_num(d.delta_loc)));
self.out.push_str("| Metric | Rating | Details |\n| :--- | :---: | :--- |\n");
let _ = writeln!(self.out, "| **Final Score** | **{}** | **{}/7 Stars**{} |", star_string(s.stars), s.stars, d_stars);
let _ = writeln!(self.out, "| Code Health | {} | {}/7 Stars{} |", star_string(s.code_stars), s.code_stars, d_code);
self.render_coverage_row(s);
let _ = writeln!(self.out, "| System Volume | {} | {}/7 Stars ({} func LOC){} |\n", star_string(s.volume_stars), s.volume_stars, s.total_loc, d_vol);
}
#[rustfmt::skip]
fn render_coverage_row(&mut self, s: &Score) {
let d_cov = self.res.delta.and_then(|d| d.delta_cov).map_or(String::new(), |c| format!(" `[{}]`", crate::history::format_delta_pct(c)));
if let (Some(pct), Some(st)) = (s.cov_pct, s.cov_stars) {
let _ = writeln!(self.out, "| Test Coverage | {} | {}/7 Stars ({:.1}% churn-weighted){} |", star_string(st), st, pct, d_cov);
} else {
let hint = if crate::coverage::has_llvm_cov() { "No coverage data generated (Run 'cargo sig -a')" } else { "cargo-llvm-cov not installed (Run 'cargo install cargo-llvm-cov')" };
let _ = writeln!(self.out, "| Test Coverage | N/A | {hint} |");
}
}
#[rustfmt::skip]
fn render_history(&mut self) {
if self.res.history.is_empty() { return; }
self.out.push_str("## Historical Maintainability Trajectory\n\n");
self.out.push_str("| Date | Commit | Score | Code Health | Coverage | System Volume | Violations | Duplication |\n| :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |\n");
for rec in self.res.history.iter().rev().take(10) {
let cov = rec.cov_pct.map_or_else(|| "N/A".to_string(), |p| format!("{p:.1}%"));
let _ = writeln!(
self.out,
"| {} | `{}` | {}/7 | {}/7 | {} | {} LOC | {} | {:.1}% |",
rec.date, rec.commit, rec.stars, rec.code_stars, cov, rec.total_loc, rec.total_violations, rec.dup_pct
);
}
self.out.push('\n');
}
#[rustfmt::skip]
fn render_risk_table(&mut self) {
let s = self.res.score;
self.out.push_str("### Risk Profile Distribution\n\n| Risk Tier | Codebase Volume % |\n| :--- | :---: |\n");
let _ = writeln!(self.out, "| Moderate Risk | {:.1}% |\n| High Risk | {:.1}% |\n| Very High Risk | {:.1}% |\n", s.pct_moderate, s.pct_high, s.pct_very_high);
}
fn render_violations(&mut self) {
self.out.push_str("## Detailed Guideline Violations\n\n");
self.render_volume_table();
self.render_complexity_table();
self.render_interface_table();
self.render_duplication_table();
}
fn render_volume_table(&mut self) {
let meta = MetricHeader {
title: "### 1. Unit Size Violations (> 15 LOC)",
empty_msg: "*No unit size violations detected.*",
val_header: "Lines of Code",
};
self.render_metric_table(meta, &filter_volume(self.res.metrics));
}
fn render_complexity_table(&mut self) {
let meta = MetricHeader {
title: "### 2. Unit Complexity Violations (> 5 Branches)",
empty_msg: "*No unit complexity violations detected.*",
val_header: "Cyclomatic Complexity",
};
self.render_metric_table(meta, &filter_complexity(self.res.metrics));
}
fn render_interface_table(&mut self) {
let meta = MetricHeader {
title: "### 3. Unit Interface Violations (> 4 Parameters)",
empty_msg: "*No interface parameter violations detected.*",
val_header: "Parameter Count",
};
self.render_metric_table(meta, &filter_interface(self.res.metrics));
}
#[rustfmt::skip]
fn render_metric_table(&mut self, meta: MetricHeader, rows: &[(&FunctionMetric, usize)]) {
let _ = writeln!(self.out, "{}\n", meta.title);
if rows.is_empty() { let _ = writeln!(self.out, "{}\n", meta.empty_msg); return; }
let _ = writeln!(self.out, "| File | Function | Line | {} |\n| :--- | :--- | :---: | :---: |", meta.val_header);
for (m, val) in rows {
let rel = format_rel_path(&m.file_path, self.root_dir);
let _ = writeln!(self.out, "| `{rel}` | `{}` | {} | **{val}** |", m.function_name, m.start_line);
}
self.out.push('\n');
}
#[rustfmt::skip]
fn render_duplication_table(&mut self) {
let dup = self.res.dup_res;
let _ = writeln!(self.out, "### 4. Code Duplication Spans ({:.1}% Total)\n", dup.percentage);
if dup.blocks.is_empty() { self.out.push_str("*No duplicated code blocks detected.*\n\n"); return; }
self.out.push_str("| File | Line Span | Duplicated Lines |\n| :--- | :---: | :---: |\n");
for b in &dup.blocks {
let rel = format_rel_path(&b.file_path, self.root_dir);
let _ = writeln!(self.out, "| `{rel}` | L{}-L{} | **{} lines** |", b.start_line, b.end_line, (b.end_line - b.start_line) + 1);
}
self.out.push('\n');
}
fn render_hotspots(&mut self) {
let (hs, fr) = get_sorted_hotspots(self.res);
self.out.push_str("## Hotspots (Risk × Churn Matrix)\n\n");
if hs.is_empty() {
self.out
.push_str("*No high-risk / high-churn hotspots detected.*\n\n");
return;
}
self.out.push_str("| Priority | File | Risk Points | Git Churn | Test Coverage | Recommendation |\n| :---: | :--- | :---: | :---: | :---: | :--- |\n");
self.render_hotspot_rows(&hs, &fr);
self.out.push('\n');
}
#[rustfmt::skip]
fn render_hotspot_rows(&mut self, hs: &[PathBuf], fr: &HashMap<PathBuf, usize>) {
for row in collect_hotspot_rows(hs, fr, self.res, self.root_dir) {
let _ = writeln!(self.out, "| #{} | `{}` | {} | {} commits | {} | {} |", row.idx, row.rel_path, row.risk, row.churn, row.cov, row.rec);
}
}
fn render_architecture(&mut self) {
self.out.push_str("## Architecture & Component Balance\n\n");
if super::is_balanced(self.res.metrics) {
self.out.push_str(
"- **Component Balance:** All modules are balanced (< 50% codebase share each).\n",
);
} else {
self.out.push_str(
"- **Component Balance:** [WARNING] One component exceeds 50% of the entire codebase.\n",
);
}
self.render_cycles();
self.out.push('\n');
}
#[rustfmt::skip]
fn render_cycles(&mut self) {
let cycles = self.res.graph.detect_cycles();
if cycles.is_empty() { self.out.push_str("- **Circular Dependencies:** None detected.\n"); return; }
let _ = writeln!(self.out, "- **Circular Dependencies:** {} detected!", cycles.len());
for (i, c) in cycles.iter().take(5).enumerate() {
let chain: Vec<String> = c.iter().map(|p| format!("`{}`", format_rel_path(p, self.root_dir))).collect();
let _ = writeln!(self.out, " - Cycle #{}: {} -> {}", i + 1, chain.join(" -> "), chain[0]);
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::coverage::Coverage;
use tempfile::tempdir;
#[test]
fn test_render_markdown_empty() {
let dir = tempdir().unwrap();
let graph = crate::coupling::CouplingGraph::default();
let churns = HashMap::new();
let dup_res = crate::duplication::DuplicationResult::default();
let score = Score {
stars: 7,
code_stars: 7,
cov_stars: Some(7),
cov_pct: Some(100.0),
volume_stars: 7,
total_loc: 0,
pct_moderate: 0.0,
pct_high: 0.0,
pct_very_high: 0.0,
};
let res = AnalysisResult {
metrics: &[],
churns: &churns,
cov: &None,
score: &score,
dup_res: &dup_res,
graph: &graph,
delta: None,
history: &[],
};
let md = render_markdown(&res, dir.path());
assert!(md.contains("# SIG Maintainability Audit Report"));
assert!(md.contains("No unit size violations detected."));
}
#[test]
fn test_render_markdown_with_violations() {
let dir = tempdir().unwrap();
let m1 = FunctionMetric {
file_path: dir.path().join("src/lib.rs"),
function_name: "complex_fn".to_string(),
start_line: 10,
lines_of_code: 50,
parameter_count: 6,
cyclomatic_complexity: 8,
};
let metrics = vec![m1];
let mut churns = HashMap::new();
churns.insert(dir.path().join("src/lib.rs"), 10);
let mut cov_map = HashMap::new();
cov_map.insert(
dir.path().join("src/lib.rs"),
Coverage { hit: 5, total: 10 },
);
let cov = Some(cov_map);
let dup_res = crate::duplication::DuplicationResult {
percentage: 5.0,
blocks: vec![crate::duplication::DuplicationBlock {
file_path: dir.path().join("src/lib.rs"),
start_line: 1,
end_line: 10,
}],
};
let graph = crate::coupling::CouplingGraph::default();
let score = Score {
stars: 4,
code_stars: 4,
cov_stars: Some(4),
cov_pct: Some(50.0),
volume_stars: 7,
total_loc: 50,
pct_moderate: 0.0,
pct_high: 100.0,
pct_very_high: 0.0,
};
let res = AnalysisResult {
metrics: &metrics,
churns: &churns,
cov: &cov,
score: &score,
dup_res: &dup_res,
graph: &graph,
delta: None,
history: &[],
};
let md = render_markdown(&res, dir.path());
assert!(md.contains("`complex_fn`"));
assert!(md.contains("L1-L10"));
assert!(md.contains("src/lib.rs"));
let report_path = generate_markdown_report(&res, dir.path()).unwrap();
assert!(report_path.exists());
}
}