//! Report renderers (text / markdown / tweet / rokha_app / self-contained
//! HTML) + a durable report store (writes .md + .json artifacts and an
//! index; the .html sibling is opt-in).
use crate::types::{AuditResult, Verdict};
use anyhow::Result;
use serde_json::json;
use std::fs;
use std::path::{Path, PathBuf};
/// The live dashboard UI — also the template for the static per-audit HTML
/// artifact (same pixels, data baked in, zero network).
pub const DASHBOARD_HTML: &str = include_str!("dashboard.html");
fn verdict_str(v: Verdict) -> &'static str {
match v {
Verdict::Avoid => "AVOID",
Verdict::HighRisk => "HIGH RISK",
Verdict::Caution => "CAUTION",
Verdict::Fair => "FAIR",
Verdict::LowRisk => "LOW RISK",
Verdict::Unknown => "UNKNOWN",
}
}
fn verdict_emoji(v: Verdict) -> &'static str {
match v {
Verdict::Avoid => "🔴",
Verdict::HighRisk => "🟠",
Verdict::Caution => "🟡",
Verdict::Fair => "🟢",
Verdict::LowRisk => "✅",
Verdict::Unknown => "⚪",
}
}
fn sev_emoji(s: crate::types::Severity) -> &'static str {
use crate::types::Severity::*;
match s {
Critical => "🛑",
Danger => "🔴",
Warning => "⚠️",
Info => "ℹ️",
Good => "✅",
}
}
fn usd(n: Option<f64>) -> String {
match n {
None => "—".into(),
Some(v) => {
let int = v.round() as i64;
let digits = int.abs().to_string();
let mut s = String::new();
for (i, c) in digits.chars().enumerate() {
if i > 0 && (digits.len() - i) % 3 == 0 {
s.push(',');
}
s.push(c);
}
format!("${s}")
}
}
}
pub fn render_text(r: &AuditResult) -> String {
let mut l = vec![];
l.push(format!(
"Solwatch audit — {} ({})",
r.token.symbol.clone().unwrap_or_else(|| "?".into()),
r.token.name.clone().unwrap_or_else(|| "unknown".into())
));
l.push(format!(" {} · Solana", r.address));
l.push(format!(
" {} {} score {}/100",
verdict_emoji(r.verdict),
verdict_str(r.verdict),
r.score
));
l.push(format!(
" mcap {} · 24h vol {} · holders {}{}",
usd(r.token.market_cap_usd),
usd(r.token.volume_24h_usd),
r.token
.holders_count
.map(|h| h.to_string())
.unwrap_or_else(|| "—".into()),
r.token
.launchpad
.as_ref()
.map(|l| format!(" · via {l}"))
.unwrap_or_default()
));
l.push(String::new());
l.push(" Flags:".into());
for f in &r.flags {
l.push(format!(
" {} {} — {}",
sev_emoji(f.severity),
f.title,
f.detail
));
}
if !r.coverage_gaps.is_empty() {
l.push(String::new());
l.push(format!(
" ⚠ INCOMPLETE SCAN — affected checks did NOT run; unknown ≠ safe: {}",
r.coverage_gaps.join("; ")
));
}
if !r.warnings.is_empty() {
l.push(String::new());
l.push(format!(" Notes: {}", r.warnings.join("; ")));
}
l.push(String::new());
if let Some(u) = &r.rokha_url {
l.push(format!(" View in Rokha: {u}"));
}
l.push(format!(" scanned {}", r.scanned_at));
l.join("\n")
}
pub fn render_markdown(r: &AuditResult) -> String {
let mut l = vec![];
l.push(format!(
"# {} {} — {} ({}/100)",
verdict_emoji(r.verdict),
r.token.symbol.clone().unwrap_or_else(|| "?".into()),
verdict_str(r.verdict),
r.score
));
l.push(String::new());
l.push(format!(
"**{}** · `{}` · Solana{}",
r.token
.name
.clone()
.unwrap_or_else(|| "Unknown token".into()),
r.address,
r.token
.launchpad
.as_ref()
.map(|lp| format!(" · launched via {lp}"))
.unwrap_or_default()
));
l.push(String::new());
l.push("| Market cap | 24h volume | Holders | Scanned |".into());
l.push("|---|---|---|---|".into());
l.push(format!(
"| {} | {} | {} | {} |",
usd(r.token.market_cap_usd),
usd(r.token.volume_24h_usd),
r.token
.holders_count
.map(|h| h.to_string())
.unwrap_or_else(|| "—".into()),
r.scanned_at[..r.scanned_at.len().min(16)].replace('T', " ")
));
l.push(String::new());
l.push("## Findings".into());
l.push(String::new());
for f in &r.flags {
l.push(format!(
"- {} **{}** — {}",
sev_emoji(f.severity),
f.title,
f.detail
));
}
if let Some(bu) = r.sections.get("bundles") {
if bu
.get("analyzed")
.and_then(|v| v.as_bool())
.unwrap_or(false)
{
l.push(String::new());
l.push("## Launch window".into());
l.push(format!(
"{}% of supply sniped by {} wallets ({} in the exact creation slot); snipers still hold {}%. Dev allocation {}%.",
bu.get("pctSupplySniped").map(|v| v.to_string()).unwrap_or_else(|| "—".into()),
bu.get("snipers").map(|v| v.to_string()).unwrap_or_else(|| "—".into()),
bu.get("sameSlotBuyers").map(|v| v.to_string()).unwrap_or_else(|| "—".into()),
bu.get("pctSnipersStillHold").map(|v| v.to_string()).unwrap_or_else(|| "—".into()),
bu.get("pctDevAllocation").map(|v| v.to_string()).unwrap_or_else(|| "—".into()),
));
}
}
if let Some(cl) = r
.sections
.pointer("/cluster/findings")
.and_then(|v| v.as_array())
.filter(|c| !c.is_empty())
{
l.push(String::new());
l.push("## Linked wallets".into());
l.push(String::new());
// Every row states the evidence that produced it and how far that
// evidence goes. `proven` means we read the transaction; `lead` means
// we did not, and the row is printed anyway so nobody mistakes our
// silence for a clean bill of health.
l.push("| # | wallets | holds now | bought | evidence | confidence |".into());
l.push("|---|---|---|---|---|---|".into());
for (i, c) in cl.iter().enumerate() {
let conf = c.get("confidence").and_then(|v| v.as_str()).unwrap_or("");
l.push(format!(
"| {} | {} | {}% | {} | {} | {} |",
c.get("id").and_then(|v| v.as_u64()).unwrap_or(i as u64 + 1),
c.get("wallets")
.and_then(|w| w.as_array())
.map(|w| w.len())
.unwrap_or(0),
c.get("pct_combined")
.and_then(|v| v.as_f64())
.unwrap_or(0.0),
c.get("pct_bought")
.and_then(|v| v.as_f64())
.map(|v| format!("{v}%"))
.unwrap_or_else(|| "—".into()),
c.get("evidence")
.and_then(|v| v.as_str())
.unwrap_or("")
.replace('_', " "),
match conf {
"proven" =>
if c.get("proof").map(|p| !p.is_null()).unwrap_or(false) {
"**proven** ⚡ Jito"
} else {
"**proven**"
},
"probable" => "probable",
"lead" => "_lead only_",
other => other,
},
));
}
for c in cl {
if let Some(n) = c.get("note").and_then(|v| v.as_str()) {
l.push(format!("- {n}"));
}
}
if let Some(ec) = r.sections.pointer("/cluster/effective_concentration") {
if !ec.is_null() {
l.push(String::new());
l.push(format!(
"Entity top-10 is **at least {}%** (raw per-wallet: {}%); the largest single entity at least {}%. These are floors — every link we did not find can only raise them.",
ec.get("top10_entity_pct_floor")
.and_then(|v| v.as_f64())
.unwrap_or(0.0),
ec.get("top10_raw_pct")
.and_then(|v| v.as_f64())
.unwrap_or(0.0),
ec.get("largest_entity_pct_floor")
.and_then(|v| v.as_f64())
.unwrap_or(0.0),
));
}
}
// What this pass structurally CANNOT see, printed on every report —
// including the clean ones, where it matters most. A reader who does
// not know the holder set stops at 20 wallets will read "no clusters
// found" as "no clusters exist".
if let Some(scope) = r.sections.pointer("/cluster/scope") {
l.push(String::new());
l.push(format!(
"**How far this went** — {} wallets examined ({} holders, {} launch buyers), {} funding hop(s), {} transaction(s) sampled for direct transfers. Coverage: **{}**.",
scope.get("wallets_analyzed").and_then(|v| v.as_u64()).unwrap_or(0),
scope.get("holders_analyzed").and_then(|v| v.as_u64()).unwrap_or(0),
scope.get("snipers_analyzed").and_then(|v| v.as_u64()).unwrap_or(0),
scope.get("funder_hops").and_then(|v| v.as_u64()).unwrap_or(0),
scope.get("transfer_txs_sampled").and_then(|v| v.as_u64()).unwrap_or(0),
scope.get("coverage").and_then(|v| v.as_str()).unwrap_or("unknown"),
));
if let Some(limits) = scope.get("limits").and_then(|v| v.as_array()) {
l.push(String::new());
for lim in limits {
if let Some(s) = lim.as_str() {
l.push(format!("- {s}"));
}
}
}
if let Some(n) = scope.get("note").and_then(|v| v.as_str()) {
if !n.is_empty() {
l.push(format!("- {n}"));
}
}
}
}
if !r.coverage_gaps.is_empty() {
l.push(String::new());
l.push(format!(
"> ⚠ **INCOMPLETE SCAN** — the affected checks did NOT run, and unknown is not the same as safe: {}. Treat the score as a ceiling.",
r.coverage_gaps.join("; ")
));
}
if !r.warnings.is_empty() {
l.push(String::new());
l.push(format!("> Notes: {}", r.warnings.join("; ")));
}
l.push(String::new());
if let Some(u) = &r.rokha_url {
l.push(format!("**[View in Rokha →]({u})**"));
l.push(String::new());
}
l.push(
"_Solwatch · real on-chain data · a SNAPSHOT of the chain at scan time (flags \
and score move as the chain moves — compare `flags[]`, not bare scores) · \
not financial advice._"
.into(),
);
l.join("\n")
}
pub fn render_tweet(r: &AuditResult) -> String {
let top: Vec<String> = r
.flags
.iter()
.filter(|f| {
matches!(
f.severity,
crate::types::Severity::Critical | crate::types::Severity::Danger
)
})
.take(2)
.map(|f| f.title.replace('🍯', "").trim().to_string())
.collect();
let flag_line = if top.is_empty() {
String::new()
} else {
format!(" {}", top.join("; "))
};
// An UNKNOWN verdict means nothing could be read — printing "0/100" beside
// it reads as a catastrophic score rather than an absent one.
let score_part = if r.verdict == crate::types::Verdict::Unknown {
String::new()
} else {
format!(" ({}/100)", r.score)
};
let base = format!(
"{} ${} on Solana — {}{}.{}",
verdict_emoji(r.verdict),
r.token.symbol.clone().unwrap_or_else(|| "?".into()),
verdict_str(r.verdict),
score_part,
flag_line
);
// Loud honesty on the most public surface. This marker used to be withheld
// from risk verdicts on the reasoning that "risk verdicts already warn" —
// but they warn about RISK, not about COVERAGE. That is the reputational
// landmine: a tweet accusing named wallets of dev-funded sniping, made on a
// partial scan the code itself labels a floor, went out with no qualifier
// while a CAUTION token got one. An accusation needs the hedge MORE than a
// reassurance does, because compression already strips it: only `f.title`
// survives into the post, and every "at least" / "treat this as a floor"
// qualifier lives in `f.detail`.
let coverage_full = r.coverage_gaps.is_empty()
&& r.sections
.pointer("/cluster/scope/coverage")
.and_then(|v| v.as_str())
== Some("full");
let base = if coverage_full {
base
} else {
format!("{base} ⚠ partial scan — figures are floors")
};
let tail = format!(
" mcap {}. Audited by @Rokha_ai",
usd(r.token.market_cap_usd)
);
let mut out = format!("{base}{tail}");
if out.chars().count() > 280 {
let keep = 280usize.saturating_sub(tail.chars().count() + 1);
out = format!("{}…{}", base.chars().take(keep).collect::<String>(), tail);
}
out.chars().take(280).collect()
}
/// Build the Rokha APP-view block: the documented, repeatable contract for a
/// rig to get a native render in Rokha's output rail. A rig whose final step
/// outputs `{ "rokha_app": … }` (this JSON already carries it) is render-ready.
pub fn render_rokha_app(r: &AuditResult) -> serde_json::Value {
let mut metrics = vec![];
let mut push = |label: &str, value: String, tone: &str| {
metrics.push(json!({"label": label, "value": value, "tone": tone}));
};
if let Some(m) = r.token.market_cap_usd {
push("Market cap", usd(Some(m)), "neutral");
}
if let Some(v) = r.token.volume_24h_usd {
push("24h volume", usd(Some(v)), "neutral");
}
if let Some(h) = r.token.holders_count {
push("Holders", h.to_string(), "neutral");
}
if let Some(t) = r
.sections
.pointer("/liquidity/totalLiquidityUsd")
.and_then(|v| v.as_f64())
.filter(|t| *t > 0.0)
{
push(
"Liquidity",
usd(Some(t)),
if t < 5000.0 { "warn" } else { "neutral" },
);
}
if let Some(p) = r
.sections
.pointer("/bundles/pctSupplySniped")
.and_then(|v| v.as_f64())
{
push(
"Supply sniped",
format!("{p}%"),
if p >= 40.0 {
"bad"
} else if p >= 15.0 {
"warn"
} else {
"ok"
},
);
}
if let Some(p) = r
.sections
.pointer("/holders/top10Pct")
.and_then(|v| v.as_f64())
{
push(
"Top-10 hold",
format!("{p}%"),
if p >= 60.0 {
"bad"
} else if p >= 30.0 {
"warn"
} else {
"ok"
},
);
}
if let Some(p) = r
.sections
.pointer("/cluster/effective_concentration/largest_entity_pct_floor")
.and_then(|v| v.as_f64())
.filter(|p| *p > 0.0)
{
push(
"Largest entity",
format!("≥{p}%"),
if p >= 20.0 {
"bad"
} else if p >= 10.0 {
"warn"
} else {
"ok"
},
);
}
if let Some(p) = r
.sections
.pointer("/cluster/effective_concentration/top10_entity_pct_floor")
.and_then(|v| v.as_f64())
.filter(|p| *p > 0.0)
{
push(
"Entity top-10",
format!("≥{p}%"),
if p >= 60.0 {
"bad"
} else if p >= 30.0 {
"warn"
} else {
"ok"
},
);
}
if let Some(cl) = r
.sections
.pointer("/cluster/findings")
.and_then(|v| v.as_array())
{
let proven = cl
.iter()
.any(|c| c.get("proof").map(|p| !p.is_null()).unwrap_or(false));
// "no" would be evidence-of-absence framing when the proof API was
// simply unreachable — absence of evidence must read as unchecked.
let jito_live = r
.sections
.pointer("/cluster/scope/jitoApiOk")
.and_then(|v| v.as_bool())
.unwrap_or(true);
if !cl.is_empty() {
push(
"Jito-proven",
if proven {
"yes".into()
} else if jito_live {
"no".into()
} else {
"unchecked".into()
},
if proven {
"bad"
} else if jito_live {
"neutral"
} else {
"warn"
},
);
}
}
if let Some(s) = r
.sections
.pointer("/market/organicScore")
.and_then(|v| v.as_f64())
{
let s = s.round();
push(
"Organic score",
format!("{s}/100"),
if s >= 60.0 {
"ok"
} else if s >= 25.0 {
"warn"
} else {
"bad"
},
);
}
let findings: Vec<String> = r
.flags
.iter()
.map(|f| format!("- {} **{}** — {}", sev_emoji(f.severity), f.title, f.detail))
.collect();
let mut sections = vec![json!({"heading": "Findings", "markdown": findings.join("\n")})];
if let Some(sn) = r
.sections
.pointer("/bundles/topSnipers")
.and_then(|v| v.as_array())
{
if !sn.is_empty() {
let rows: Vec<_> = sn
.iter()
.map(|s| {
json!([
s.get("owner").and_then(|v| v.as_str()).unwrap_or("?"),
// `null` here means the probe never resolved this
// wallet's balance. Rendering that as "0%" published
// "still holds 0%" next to a real address — a specific
// public claim that a named trader dumped their bag,
// asserted from a measurement we never took.
match s.get("pct").and_then(|v| v.as_f64()) {
Some(p) => format!("{p}%"),
None => "—".to_string(),
},
match s.get("heldPct").and_then(|v| v.as_f64()) {
Some(p) => format!("{p}%"),
None => "— (not checked)".to_string(),
},
if s.get("sameSlot").and_then(|v| v.as_bool()).unwrap_or(false) {
"yes"
} else {
""
},
])
})
.collect();
sections.push(json!({"heading": "Launch snipers", "table": {
"columns": ["wallet", "bought at launch", "still holds", "same-slot"],
"rows": rows,
}}));
}
}
if let Some(cl) = r
.sections
.pointer("/cluster/findings")
.and_then(|v| v.as_array())
{
if !cl.is_empty() {
let rows: Vec<_> = cl
.iter()
.enumerate()
.map(|(i, c)| {
json!([
format!(
"#{}",
c.get("id").and_then(|v| v.as_u64()).unwrap_or(i as u64 + 1)
),
c.get("wallets")
.and_then(|w| w.as_array())
.map(|w| w.len().to_string())
.unwrap_or_default(),
format!(
"{}%",
c.get("pct_combined")
.and_then(|v| v.as_f64())
.unwrap_or(0.0)
),
c.get("pct_bought")
.and_then(|v| v.as_f64())
.map(|v| format!("{v}%"))
.unwrap_or_else(|| "—".into()),
c.get("evidence")
.and_then(|v| v.as_str())
.unwrap_or("")
.replace('_', " "),
// The confidence tier IS the headline column — a reader
// scanning this table must not have to infer how much
// any row is worth from the evidence name alone.
match c.get("confidence").and_then(|v| v.as_str()).unwrap_or("") {
"proven" =>
if c.get("proof").map(|p| !p.is_null()).unwrap_or(false) {
"proven (Jito)".to_string()
} else {
"proven".to_string()
},
other => other.to_string(),
},
])
})
.collect();
sections.push(json!({"heading": "Linked wallets", "table": {
"columns": ["#", "wallets", "holds now", "bought at launch", "evidence", "confidence"],
"rows": rows,
}}));
}
}
// The limits ride the app block too — the rail renders this beside the
// score, which is exactly where an over-read happens.
if let Some(limits) = r
.sections
.pointer("/cluster/scope/limits")
.and_then(|v| v.as_array())
.filter(|l| !l.is_empty())
{
let md: Vec<String> = limits
.iter()
.filter_map(|v| v.as_str())
.map(|s| format!("- {s}"))
.collect();
sections.push(json!({
"heading": "What the wallet-link pass cannot see",
"markdown": md.join("\n"),
}));
}
json!({
"title": format!("Solwatch audit — ${}", r.token.symbol.clone().unwrap_or_else(|| "?".into())),
"subject": r.address,
"verdict": verdict_str(r.verdict).replace(' ', "_").to_lowercase(),
"score": r.score,
"metrics": metrics,
"sections": sections,
// The APP rail and public rig product pages render THIS block — the
// most-seen surface was previously the least disclosed, showing a clean
// score card for a run with a degraded scan. Coverage travels with the
// score everywhere the score goes.
"coverage": if r.coverage_gaps.is_empty() { "full" } else { "partial" },
"coverageGaps": r.coverage_gaps,
"warnings": r.warnings,
})
}
/// One self-contained HTML file — the exact dashboard card with this audit's
/// data baked in (inlined CSS/JS, fetch stubbed, no network). This is how a
/// run inside an egress-only sandbox ships its "frontend" OUT as an artifact:
/// the file renders anywhere, including a hard-sandboxed srcdoc iframe.
pub fn render_html(r: &AuditResult) -> String {
// `</` would close the script tag early inside embedded JSON.
let data = serde_json::to_string(r)
.unwrap_or_else(|_| "null".into())
.replace("</", "<\\/");
let stub = format!(
"<script>\nconst __AUDIT = {data};\nwindow.fetch = async (u) => {{\n const s = String(u);\n if (s.includes('/api/audit')) {{\n const m = s.match(/[?&]address=([^&]*)/);\n const a = m ? decodeURIComponent(m[1]) : '';\n const baked = (__AUDIT && __AUDIT.address) || '';\n if (a && a.toLowerCase() !== baked.toLowerCase() && window.parent !== window) {{\n window.parent.postMessage({{ rokha: 'app_action', action: 'run', input: a.slice(0, 4000) }}, '*');\n return {{ json: async () => ({{ __rokha_pending: true }}) }};\n }}\n return {{ json: async () => __AUDIT }};\n }}\n return {{ json: async () => [] }};\n}};\n</script>\n<script>"
);
let html = DASHBOARD_HTML.replacen("<script>", &stub, 1);
html.replacen(
"</script>\n</body>",
"if (__AUDIT && __AUDIT.address) audit(__AUDIT.address);</script>\n</body>",
1,
)
}
// ---- report store ----
pub fn default_report_dir() -> PathBuf {
std::env::var("SOLWATCH_OUT")
.map(PathBuf::from)
.unwrap_or_else(|_| {
std::env::current_dir()
.unwrap_or_default()
.join("solwatch-reports")
})
}
fn safe(s: &str) -> String {
let out: String = s
.chars()
.filter(|c| c.is_ascii_alphanumeric())
.take(16)
.collect();
if out.is_empty() {
"token".into()
} else {
out
}
}
/// Write the durable report artifacts: `.md` + `.json` + the index, always;
/// the self-contained `.html` dashboard sibling only when `html` is true
/// (opt-in — `--report-html` on the CLI; `--app-html` is the standalone
/// dashboard path and doesn't ride through here).
pub fn write_report(r: &AuditResult, dir: &Path, html: bool) -> Result<String> {
fs::create_dir_all(dir)?;
let ts = r.scanned_at.replace([':', '.'], "-");
let base = format!(
"{}-{}-{}",
safe(r.token.symbol.as_deref().unwrap_or("token")),
&r.address[..8.min(r.address.len())],
ts
);
let md_file = format!("{base}.md");
fs::write(dir.join(&md_file), render_markdown(r))?;
fs::write(
dir.join(format!("{base}.json")),
serde_json::to_string_pretty(r)?,
)?;
if html {
fs::write(dir.join(format!("{base}.html")), render_html(r))?;
}
let idx_path = dir.join("index.json");
let mut index: Vec<serde_json::Value> = fs::read_to_string(&idx_path)
.ok()
.and_then(|s| serde_json::from_str(&s).ok())
.unwrap_or_default();
index.insert(0, json!({
"file": md_file, "symbol": r.token.symbol, "address": r.address,
"score": r.score, "verdict": verdict_str(r.verdict).replace(' ', "_"), "scannedAt": r.scanned_at,
}));
index.truncate(500);
fs::write(&idx_path, serde_json::to_string_pretty(&index)?)?;
Ok(md_file)
}
pub fn list_reports(dir: &Path) -> Vec<serde_json::Value> {
fs::read_to_string(dir.join("index.json"))
.ok()
.and_then(|s| serde_json::from_str(&s).ok())
.unwrap_or_default()
}