Supporting "markdown" scan output format (#92)

Author: sureshcsdp

README.md

@@ -13,6 +13,7 @@ Like `tfsec` for Terraform or `trivy` for containers — CleanCloud scans your c
 - **20 high-signal detection rules:** orphaned volumes, idle databases, empty load balancers, and more
 - **Estimated monthly waste:** per finding and aggregate
 - **CI-native enforcement (opt-in):** `--fail-on-confidence HIGH` or `--fail-on-cost 100` gates your pipeline
+- **Multiple output formats:** human-readable, JSON, CSV, and markdown (paste into GitHub PRs or Slack)
 - **Read-only by design:** no deletions, no tag changes, no mutations — ever
 - **No agents. No telemetry. No SaaS.** Runs in your environment, data never leaves
 
@@ -21,8 +22,22 @@ Like `tfsec` for Terraform or `trivy` for containers — CleanCloud scans your c
 - Scheduled hygiene scans — cron job or weekly CI run to catch drift
 - CI/CD enforcement gates — fail builds when waste exceeds your threshold
 
-> Bug reports and feedback very welcome via [issues](https://github.com/cleancloud-io/cleancloud/issues).
+```
+Found 6 hygiene issues:
 
+1. [AWS] Unattached EBS Volume       — $40/month
+2. [AWS] Idle NAT Gateway            — $32.40/month
+3. [AWS] Unattached Elastic IP       — $0/month
+...
+
+Estimated monthly waste: ~$147
+Regions scanned: us-east-1, us-west-2, eu-west-1
+```
+
+## What users say
+
+> "Solid discovery tool that bubbles up potential savings. Easy to install and use!"
+> — [Reddit user](https://www.reddit.com/r/AZURE/comments/1rm7an5/comment/o8zfv6a/)
 ---
 
 ## Get Started
@@ -139,7 +154,40 @@ Regions scanned: us-east-1, us-west-2, eu-west-1 (auto-detected)
 
 No cloud account yet? `cleancloud demo` shows sample output without any credentials.
 
-For full output examples including `doctor`, JSON, and CSV: [`docs/example-outputs.md`](docs/example-outputs.md)
+### Shareable markdown report
+
+```bash
+cleancloud scan --provider aws --all-regions --output markdown
+```
+
+Prints a grouped summary you can paste directly into a GitHub PR comment, Slack message, or issue:
+
+```markdown
+## CleanCloud Scan Results
+
+**Provider:** AWS
+**Regions:** us-east-1, us-west-2, eu-west-1
+**Scanned:** 2026-03-07
+**Estimated monthly waste:** ~$147
+
+**Total findings:** 6
+
+| Finding | Count | Est. Monthly Cost |
+|---------|------:|------------------:|
+| Unattached EBS Volume | 2 | ~$115 |
+| Idle NAT Gateway | 1 | ~$32 |
+| Unattached Elastic IP | 1 | ~$0 |
+| Detached ENI | 1 | — |
+| CloudWatch Log Group: Infinite Retention | 1 | — |
+
+**Confidence:** high: 3 · medium: 3
+
+> Generated by [CleanCloud](https://github.com/cleancloud-io/cleancloud) — read-only cloud hygiene scanner for AWS and Azure.
+```
+
+Save to a file with `--output-file results.md`. Without `--output-file`, it prints to stdout.
+
+For full output examples including `doctor`, JSON, CSV, and markdown: [`docs/example-outputs.md`](docs/example-outputs.md)
 
 ---
 
@@ -229,18 +277,6 @@ Setup guides: [AWS](docs/aws.md) · [Azure](docs/azure.md)
 
 ---
 
-## What Users Are Saying
-
-> "Solid discovery tool that bubbles up potential savings. Easy to install and use!
->
-> The VPN gateway showed all of mine had no active connections, but 3 of 4 show Connected
-> and have recent data. I know why the 4th one is not connected and this helps remind me
-> to pester the network team about it :)"
->
-> — [Reddit user](https://www.reddit.com/r/AZURE/comments/1rm7an5/comment/o8zfv6a/)
-
----
-
 ## Roadmap
 
 - Additional AWS rules (S3 lifecycle, stopped EC2 instances)
@@ -262,8 +298,10 @@ Setup guides: [AWS](docs/aws.md) · [Azure](docs/azure.md)
 
 ---
 
-**Found a bug?** [Open an issue](https://github.com/cleancloud-io/cleancloud/issues) ·
-**Feature request?** [Start a discussion](https://github.com/cleancloud-io/cleancloud/discussions) ·
+**Found a bug?** [Open an issue](https://github.com/cleancloud-io/cleancloud/issues)
+
+**Feature request?** [Start a discussion](https://github.com/cleancloud-io/cleancloud/discussions)
+
 **Questions?** suresh@getcleancloud.com
 
 [MIT License](LICENSE)

cleancloud/output/markdown.py

@@ -0,0 +1,106 @@
+from collections import defaultdict
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from cleancloud.core.finding import Finding
+
+
+def _group_findings(findings: List[Finding]) -> List[Dict]:
+    """Group findings by title, summing counts and costs."""
+    groups: Dict[str, Dict] = defaultdict(lambda: {"count": 0, "cost": 0.0, "has_cost": False})
+
+    for f in findings:
+        key = f.title
+        groups[key]["count"] += 1
+        if f.estimated_monthly_cost_usd is not None:
+            groups[key]["cost"] += f.estimated_monthly_cost_usd
+            groups[key]["has_cost"] = True
+
+    # Sort by cost descending, then count descending
+    return sorted(
+        [{"title": k, **v} for k, v in groups.items()],
+        key=lambda x: (x["cost"], x["count"]),
+        reverse=True,
+    )
+
+
+def write_markdown(
+    findings: List[Finding],
+    summary: dict,
+    output_path: Optional[Path] = None,
+) -> Optional[str]:
+    lines = []
+
+    provider = summary.get("provider", "").upper()
+    scanned_at = summary.get("scanned_at", "")[:10]  # date only
+
+    # Header
+    lines.append("## CleanCloud Scan Results")
+    lines.append("")
+
+    # Metadata
+    regions = summary.get("regions_scanned", [])
+    if isinstance(regions, list):
+        regions_str = ", ".join(regions) if regions else "—"
+    else:
+        regions_str = str(regions)
+
+    subscriptions = summary.get("subscriptions_scanned", [])
+    if subscriptions:
+        lines.append(f"**Provider:** {provider}  ")
+        lines.append(f"**Subscriptions:** {', '.join(subscriptions)}  ")
+    else:
+        lines.append(f"**Provider:** {provider}  ")
+        lines.append(f"**Regions:** {regions_str}  ")
+
+    lines.append(f"**Scanned:** {scanned_at}  ")
+
+    waste = summary.get("minimum_estimated_monthly_waste_usd")
+    if waste and waste > 0:
+        lines.append(f"**Estimated monthly waste:** ~${waste:,.0f}  ")
+
+    lines.append("")
+
+    # Findings table
+    total = summary.get("total_findings", 0)
+    if total == 0:
+        lines.append("**No hygiene issues detected.**")
+    else:
+        lines.append(f"**Total findings:** {total}")
+        lines.append("")
+        lines.append("| Finding | Count | Est. Monthly Cost |")
+        lines.append("|---------|------:|------------------:|")
+
+        for group in _group_findings(findings):
+            cost_str = f"~${group['cost']:,.0f}" if group["has_cost"] else "—"
+            lines.append(f"| {group['title']} | {group['count']} | {cost_str} |")
+
+    lines.append("")
+
+    # Confidence breakdown
+    by_conf = summary.get("by_confidence", {})
+    if by_conf:
+        conf_parts = []
+        for level in ["high", "medium", "low"]:
+            for k, v in by_conf.items():
+                label = k.value if hasattr(k, "value") else str(k)
+                if label == level:
+                    conf_parts.append(f"{label}: {v}")
+        if conf_parts:
+            lines.append(f"**Confidence:** {' · '.join(conf_parts)}")
+            lines.append("")
+
+    # Footer
+    lines.append(
+        "> Generated by [CleanCloud](https://github.com/cleancloud-io/cleancloud) — "
+        "read-only cloud hygiene scanner for AWS and Azure."
+    )
+
+    output = "\n".join(lines)
+
+    if output_path:
+        with open(output_path, "w", encoding="utf-8") as f:
+            f.write(output)
+        return None
+    else:
+        return output

cleancloud/scan/command.py

@@ -24,6 +24,7 @@
 from cleancloud.output.csv import write_csv
 from cleancloud.output.human import print_human
 from cleancloud.output.json import write_json
+from cleancloud.output.markdown import write_markdown
 from cleancloud.output.summary import _print_summary, build_summary
 from cleancloud.policy.exit_policy import (
     CONFIDENCE_ORDER,
@@ -62,12 +63,12 @@
 @click.option(
     "--output",
     default="human",
-    type=click.Choice(["human", "json", "csv"]),
+    type=click.Choice(["human", "json", "csv", "markdown"]),
 )
 @click.option(
     "--output-file",
     default=None,
-    help="Output file path (required for json/csv)",
+    help="Output file path (required for json/csv; optional for markdown — prints to stdout if omitted)",
 )
 @click.option(
     "--fail-on-findings",
@@ -229,6 +230,14 @@ def scan(
             click.echo(f"CSV output written to {output_path}")
             click.echo()
 
+        elif output == "markdown":
+            result = write_markdown(findings, summary, output_path)
+            if result is not None:
+                click.echo(result)
+            else:
+                click.echo(f"Markdown output written to {output_path}")
+            click.echo()
+
         else:
             print_human(findings)
             _print_summary(summary, region_selection_mode)

docs/example-outputs.md

@@ -1,6 +1,6 @@
 # Example Outputs
 
-Complete output examples for CleanCloud across AWS and Azure — doctor validation, human-readable scan results, and JSON output for CI/CD integration.
+Complete output examples for CleanCloud across AWS and Azure — doctor validation, human-readable scan results, JSON output for CI/CD integration, and markdown for sharing in GitHub PRs or Slack.
 
 ---
 
@@ -12,6 +12,8 @@ Complete output examples for CleanCloud across AWS and Azure — doctor validati
 - [Scan — Azure (Human-Readable)](#scan--azure-human-readable)
 - [Scan — AWS (JSON)](#scan--aws-json)
 - [Scan — Azure (JSON)](#scan--azure-json)
+- [Scan — AWS (Markdown)](#scan--aws-markdown)
+- [Scan — Azure (Markdown)](#scan--azure-markdown)
 - [JSON Schema Reference](#json-schema-reference)
 
 ---
@@ -805,6 +807,71 @@ Scanned at: 2026-02-08T14:45:16+00:00
 
 ---
 
+## Scan — AWS (Markdown)
+
+`cleancloud scan --provider aws --all-regions --output markdown`
+
+Produces a grouped, cost-sorted summary you can paste directly into a GitHub PR comment, Slack message, or issue. Use `--output-file results.md` to save to a file instead.
+
+```markdown
+## CleanCloud Scan Results
+
+**Provider:** AWS
+**Regions:** us-east-1, us-west-2, eu-west-1
+**Scanned:** 2026-02-08
+**Estimated monthly waste:** ~$147
+
+**Total findings:** 6
+
+| Finding | Count | Est. Monthly Cost |
+|---------|------:|------------------:|
+| Unattached EBS Volume | 2 | ~$115 |
+| Idle NAT Gateway | 1 | ~$32 |
+| Old AMI | 1 | ~$4 |
+| Unattached Elastic IP | 1 | ~$0 |
+| CloudWatch Log Group: Infinite Retention | 1 | — |
+| Untagged Resource | 1 | — |
+
+**Confidence:** high: 2 · medium: 4
+
+> Generated by [CleanCloud](https://github.com/cleancloud-io/cleancloud) — read-only cloud hygiene scanner for AWS and Azure.
+```
+
+Findings are grouped by title (multiple instances of the same finding type are collapsed into one row with a count) and sorted by estimated cost descending.
+
+---
+
+## Scan — Azure (Markdown)
+
+`cleancloud scan --provider azure --output markdown`
+
+```markdown
+## CleanCloud Scan Results
+
+**Provider:** AZURE
+**Subscriptions:** Production, Staging
+**Scanned:** 2026-02-08
+**Estimated monthly waste:** ~$72
+
+**Total findings:** 5
+
+| Finding | Count | Est. Monthly Cost |
+|---------|------:|------------------:|
+| Load Balancer with No Backends | 1 | ~$18 |
+| Empty App Service Plan | 1 | ~$146 |
+| Unused Public IP | 1 | ~$4 |
+| Unattached Managed Disk | 1 | — |
+| Untagged Resource | 1 | — |
+
+**Confidence:** high: 3 · medium: 2
+
+> Generated by [CleanCloud](https://github.com/cleancloud-io/cleancloud) — read-only cloud hygiene scanner for AWS and Azure.
+```
+
+For Azure, the **Subscriptions** field is shown instead of **Regions**, reflecting how Azure scans are scoped.
+
+---
+
 ## JSON Schema Reference
 
 CleanCloud uses a versioned JSON schema (current: `1.0.0`). All JSON output includes a `schema_version` field for backward compatibility.