agentshield/ux/

explain.rs

use std::path::Path;

use crate::ScanReport;
use crate::config::ScanPathFilterSummary;
use crate::error::ShieldError;
use crate::rules::{AttackCategory, Finding, Severity};

use super::{hotspots, roots};

mod support;
#[cfg(test)]
mod tests;

use support::{
    confidence_for_report, coverage_summary, display_list, finding_group_summary,
    format_path_filters, gate_reason, next_actions, severity_counts,
};

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CoverageConfidence {
    High,
    Medium,
    Low,
}

impl CoverageConfidence {
    fn label(self) -> &'static str {
        match self {
            Self::High => "High",
            Self::Medium => "Medium",
            Self::Low => "Low",
        }
    }

    fn reason(self) -> &'static str {
        match self {
            Self::High => "known adapter(s) matched and source files were parsed",
            Self::Medium => "known adapter(s) matched, but code parsing coverage is limited",
            Self::Low => "no supported agent extension surface was detected",
        }
    }
}

#[derive(Debug, Clone)]
pub struct ExplainOptions {
    pub ignore_tests: bool,
}

pub fn quickstart_config_toml(fail_on: Severity, ignore_tests: bool) -> String {
    format!(
        r#"# AgentShield configuration
# Generated by `agentshield quickstart`.

[policy]
fail_on = "{fail_on}"

[scan]
ignore_tests = {ignore_tests}

[runtime.proxy]
fail_on = "block"
"#
    )
}

pub fn render_explain(report: &ScanReport, options: &ExplainOptions) -> String {
    let coverage = coverage_summary(report);
    let confidence = confidence_for_report(report);
    let runtime_findings: Vec<&Finding> = report
        .findings
        .iter()
        .filter(|finding| finding.attack_category != AttackCategory::SupplyChain)
        .collect();
    let supply_chain_findings: Vec<&Finding> = report
        .findings
        .iter()
        .filter(|finding| finding.attack_category == AttackCategory::SupplyChain)
        .collect();

    let mut output = String::new();
    output.push_str("AgentShield explain\n");
    output.push_str("===================\n\n");
    output.push_str(&format!(
        "Gate: {}\n",
        if report.verdict.pass { "PASS" } else { "FAIL" }
    ));
    output.push_str(&format!("Reason: {}\n", gate_reason(report)));
    output.push_str(&format!(
        "Security confidence: {} - {}\n\n",
        confidence.label(),
        confidence.reason()
    ));

    output.push_str("Coverage:\n");
    output.push_str(&format!(
        "- Adapters: {}\n",
        display_list(&coverage.frameworks, "none")
    ));
    output.push_str(&roots::render(report));
    output.push_str(&format!("- Targets: {}\n", coverage.targets));
    output.push_str(&format!(
        "- Source files parsed: {} ({})\n",
        coverage.source_files,
        display_list(&coverage.languages, "no code parser coverage")
    ));
    output.push_str(&format!("- Tools discovered: {}\n", coverage.tools));
    output.push_str(&format!(
        "- Dependencies checked: {}\n",
        coverage.dependencies
    ));
    output.push_str(&format!("- Lockfiles detected: {}\n", coverage.lockfiles));
    output.push_str(&format!(
        "- Test file exclusion: {}\n",
        if options.ignore_tests {
            "enabled"
        } else {
            "disabled"
        }
    ));
    output.push_str(&format!(
        "- Path filters: {}\n\n",
        format_path_filters(&report.path_filter_summary)
    ));

    output.push_str("Findings:\n");
    output.push_str(&format!(
        "- Runtime-risk findings: {}\n",
        finding_group_summary(&runtime_findings)
    ));
    output.push_str(&format!(
        "- Supply-chain hygiene: {}\n",
        finding_group_summary(&supply_chain_findings)
    ));
    output.push_str(&format!(
        "- Severity counts: {}\n\n",
        severity_counts(&report.findings)
    ));

    output.push_str(&hotspots::render(report));

    output.push_str("Next actions:\n");
    for action in next_actions(report) {
        output.push_str(&format!("- {action}\n"));
    }

    output.push_str("\nWhat this does not prove:\n");
    output.push_str("- This scan does not execute tools or prove absence of vulnerabilities.\n");
    output.push_str(
        "- It checks known risky patterns in supported agent surfaces and dependency metadata.\n",
    );

    output
}

pub fn render_no_adapter_explain(
    path: &Path,
    ignore_tests: bool,
    path_filters: &ScanPathFilterSummary,
) -> String {
    let mut output = String::new();
    output.push_str("AgentShield explain\n");
    output.push_str("===================\n\n");
    output.push_str("Gate: INCONCLUSIVE\n");
    output.push_str("Reason: no supported agent extension surface was detected.\n");
    output.push_str(&format!(
        "Security confidence: {} - {}\n\n",
        CoverageConfidence::Low.label(),
        CoverageConfidence::Low.reason()
    ));
    output.push_str("Coverage:\n");
    output.push_str("- Adapters: none\n");
    output.push_str(&format!("- Target: {}\n", path.display()));
    output.push_str(&format!(
        "- Test file exclusion: {}\n",
        if ignore_tests { "enabled" } else { "disabled" }
    ));
    output.push_str(&format!(
        "- Path filters: {}\n\n",
        format_path_filters(path_filters)
    ));
    output.push_str("Next actions:\n");
    output.push_str("- Confirm this repository contains an MCP server, OpenClaw skill, Hermes agent, CrewAI/LangChain tool, GPT Action, or Cursor Rules surface.\n");
    output.push_str("- If it does, add a framework manifest or dependency metadata that AgentShield can detect.\n");
    output.push_str("- Run `agentshield doctor .` to inspect adapter detection.\n\n");
    output.push_str("What this does not prove:\n");
    output.push_str("- This result does not mean the project is safe; it means AgentShield did not find a supported surface to scan.\n");
    output
}

pub fn is_no_adapter(error: &ShieldError) -> bool {
    matches!(error, ShieldError::NoAdapter(_))
}