@solana-epic/cli 0.1.0-beta.2 → 0.2.0-beta.0

package/dist/index.js

@@ -1,19 +1,54 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import { compareAnchorPrograms, formatHumanReport } from "@solana-epic/diff-engine";
+import { analyzePrograms, compareAccountLayouts, createUpgradeIntelligence, simulateCompatibility } from "@solana-epic/diff-engine";
 import { config } from "@solana-epic/parser";
-import { spawnSync } from "node:child_process";
+import { spawnSync, execSync } from "node:child_process";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import fs from "node:fs";
 const program = new Command();
+import { CLI_VERSION } from "./version.js";
 program
     .name("epic")
     .description("EPIC CLI for Solana Upgrade Intelligence (powered by parser-v2 Rust AST engine).")
-    .version("0.4.0")
+    .version(CLI_VERSION)
     .option("--no-banner", "Disable the startup banner");
 import { resolveParserBinary } from "./loader.js";
-import { printBanner, printInitSequence, printSection, printRuleFinding, colors, printFinalSignature, DIVIDER } from "./ui.js";
+import { printStartup, getBannerString, printInitSequence, printSection, printRuleFinding, colors, printEndSummary, printUpgradeReport, printCompatibilityReport, severityBadge, scoreBar, bandForScore, DIVIDER, ruleKnowledge } from "./ui.js";
+import { generateSarif, generateMarkdown } from "./reports.js";
+// Count Rust source files under a path (real, not fabricated metrics).
+function countRustFiles(target) {
+    let count = 0;
+    const skip = new Set([".git", "target", "node_modules", "vendor"]);
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (skip.has(entry.name))
+                    continue;
+                walk(path.join(dir, entry.name));
+            }
+            else if (entry.isFile() && entry.name.endsWith(".rs")) {
+                count++;
+            }
+        }
+    };
+    try {
+        const stat = fs.statSync(target);
+        if (stat.isFile())
+            return target.endsWith(".rs") ? 1 : 0;
+    }
+    catch {
+        return 0;
+    }
+    walk(target);
+    return count;
+}
 function findRustBinary() {
     try {
         return resolveParserBinary();
@@ -31,12 +66,13 @@ program
     const startTime = Date.now();
     try {
         const opts = program.opts();
-        printBanner(!opts.banner);
+        printStartup("Workspace Analysis", !opts.banner);
         printInitSequence([
-            "Rust AST Engine Ready",
-            "Anchor Workspace Detected",
-            "Analysis Engine Ready"
+            "Rust AST Loaded",
+            "Parsing Anchor Workspace",
+            "Building Call Graph"
         ]);
+        console.log("");
         const binary = findRustBinary();
         const resolvedPath = path.resolve(targetPath);
         const result = spawnSync(binary, [resolvedPath], { encoding: "utf-8" });
@@ -62,22 +98,19 @@ program
             console.log(colors.info("No state accounts (#[account] structures) found.\n"));
         }
         else {
-            console.log("STATE ACCOUNTS:");
+            console.log(colors.bold("STATE ACCOUNTS"));
+            console.log("");
             for (const account of report.accounts) {
                 const layoutType = account.dynamic ? "Dynamic" : "Static";
                 const prefix = account.dynamic ? colors.warning("⚠️") : "├──";
-                console.log(`${prefix} ${account.account} (${account.size} bytes) [${account.namespace}] [${layoutType}]`);
+                console.log(`${prefix} ${colors.white(account.account)} (${account.size} bytes) [${colors.dim(account.namespace)}] [${colors.cyan(layoutType)}]`);
                 if (account.dynamic) {
-                    console.log(`   └─ Warning: Dynamic size detected. Static layout realloc checks may be inaccurate.`);
+                    console.log(`   └─ ${colors.warning("Warning:")} Dynamic size detected. Static layout realloc checks may be inaccurate.`);
                 }
             }
             console.log("");
         }
-        console.log(colors.graphite(DIVIDER));
-        console.log(colors.success("Completed successfully."));
-        console.log(`${"State Accounts".padEnd(19)} ${report.accounts ? report.accounts.length : 0}`);
-        console.log(`Completed in ${Date.now() - startTime} ms\n`);
-        printFinalSignature();
+        printEndSummary(path.basename(resolvedPath) || ".", 0, 0, 0, Date.now() - startTime);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -89,18 +122,23 @@ program
     .command("check")
     .description("Compare two Solana program workspace versions and report upgrade readiness.")
     .option("-c, --config <path>", "Path to epic.toml configuration file")
+    .option("-f, --format <format>", "Output format: text, json", "text")
     .argument("<old_path>", "Path to the old program version source directory")
     .argument("<new_path>", "Path to the new program version source directory")
     .action(async (oldPath, newPath, options) => {
     const startTime = Date.now();
+    const isJson = options.format === "json";
     try {
         const opts = program.opts();
-        printBanner(!opts.banner);
-        printInitSequence([
-            "Rust AST Engine Ready",
-            "Anchor Workspace Detected",
-            "Upgrade Graph Built"
-        ]);
+        const startupShown = isJson ? false : printStartup("Upgrade Intelligence", !opts.banner);
+        if (!isJson) {
+            printInitSequence([
+                "Rust AST Loaded",
+                "Parsing Anchor Workspace",
+                "Building Call Graph"
+            ]);
+            console.log("");
+        }
         const resolvedOldPath = path.resolve(oldPath);
         const resolvedNewPath = path.resolve(newPath);
         let epicConfig;
@@ -111,26 +149,59 @@ program
             console.error(`epic.toml validation error: ${err.message}`);
             process.exit(1);
         }
-        const report = await compareAnchorPrograms(resolvedOldPath, resolvedNewPath, epicConfig);
-        console.log(formatHumanReport(report));
+        // Parse both versions once, then run BOTH the compatibility simulator
+        // (state survival) and the existing layout-diff findings off the same AST.
+        const { oldProgram, newProgram } = await analyzePrograms(resolvedOldPath, resolvedNewPath, epicConfig);
+        const compatibility = simulateCompatibility(oldProgram, newProgram, epicConfig);
+        const report = compareAccountLayouts(oldProgram, newProgram, epicConfig);
+        const intelligence = createUpgradeIntelligence(report);
+        const programName = compatibility.accounts[0]?.account || report.findings[0]?.account || path.basename(resolvedNewPath);
+        if (isJson) {
+            console.log(JSON.stringify({
+                program: programName,
+                compatibility,
+                findings: report.findings,
+                severity: report.severity
+            }, null, 2));
+            process.exit(compatibility.overall === "Blocked" ? 1 : 0);
+        }
+        // Lead with the compatibility verdict (the product), then keep the
+        // detailed layout findings below it as supporting evidence.
+        printCompatibilityReport(compatibility, { program: programName }, { skipTitle: startupShown });
+        if (report.findings.length) {
+            console.log(colors.gray(DIVIDER));
+            console.log(colors.white(colors.bold("LAYOUT FINDINGS (DETAIL)")));
+            console.log(colors.gray(DIVIDER));
+            console.log("");
+            printUpgradeReport(report, intelligence, { program: programName }, { skipTitle: true });
+            console.log("");
+        }
+        // Exit code. BLOCKED always fails CI (state corruption is non-negotiable),
+        // overriding fail_on_severity. Other outcomes respect the configured threshold.
         const severityOrder = ["SAFE", "MINOR", "WARNING", "MAJOR", "CRITICAL"];
         const thresholdIndex = severityOrder.indexOf(epicConfig.failOnSeverity);
         const reportSeverityIndex = severityOrder.indexOf(report.severity);
-        console.log(colors.graphite(DIVIDER));
-        if (thresholdIndex !== -1 && reportSeverityIndex !== -1 && reportSeverityIndex >= thresholdIndex) {
-            console.log(colors.critical(`❌ EPIC Guard Blocked: Upgrade severity is ${report.severity} (threshold: ${epicConfig.failOnSeverity}).`));
+        const severityFails = thresholdIndex !== -1 && reportSeverityIndex !== -1 && reportSeverityIndex >= thresholdIndex;
+        const blocked = compatibility.overall === "Blocked";
+        const fails = blocked || severityFails;
+        console.log(colors.gray(DIVIDER));
+        console.log("");
+        if (blocked) {
+            console.log(colors.critical(`✖ EPIC Guard Blocked: deploying would corrupt existing on-chain accounts.`));
         }
-        else {
-            console.log(colors.success(`✅ EPIC Guard Approved Upgrade.`));
+        else if (severityFails) {
+            console.log(colors.critical(`✖ EPIC Guard Blocked: Upgrade severity is ${report.severity} (threshold: ${epicConfig.failOnSeverity}).`));
         }
-        console.log(`Completed in ${Date.now() - startTime} ms\n`);
-        printFinalSignature();
-        if (thresholdIndex !== -1 && reportSeverityIndex !== -1 && reportSeverityIndex >= thresholdIndex) {
-            process.exit(1);
+        else if (compatibility.overall === "Migration-Required") {
+            console.log(colors.warning(`▲ EPIC Guard: Upgrade is safe only after the migration above is performed.`));
         }
         else {
-            process.exit(0);
+            console.log(colors.success(`✓ EPIC Guard Approved Upgrade.`));
         }
+        console.log("");
+        console.log(colors.dim(`Time: ${(Date.now() - startTime) / 1000} s`));
+        console.log("");
+        process.exit(fails ? 1 : 0);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -150,251 +221,273 @@ function getSeverityLevel(sev) {
         return 3;
     return 3;
 }
-function generateSarif(findings) {
-    const rulesMap = new Map();
-    rulesMap.set("EPIC-SEC-001", {
-        id: "EPIC-SEC-001",
-        shortDescription: {
-            text: "Owner Validation"
-        },
-        fullDescription: {
-            text: "Unchecked mutable account write without dominating owner validation."
-        },
-        helpUri: "https://github.com/akxh5/Solana-EPIC/blob/main/docs/rules/EPIC-SEC-001.md",
-        properties: {
-            category: "Security",
-            precision: "high"
-        }
-    });
-    rulesMap.set("EPIC-SEC-002", {
-        id: "EPIC-SEC-002",
-        shortDescription: {
-            text: "Missing Signer Validation"
-        },
-        fullDescription: {
-            text: "Unchecked mutable write or administrative mutation without dominating signer validation."
-        },
-        helpUri: "https://github.com/akxh5/Solana-EPIC/blob/main/docs/rules/EPIC-SEC-002.md",
-        properties: {
-            category: "Security",
-            precision: "high"
-        }
-    });
-    rulesMap.set("EPIC-SEC-003", {
-        id: "EPIC-SEC-003",
-        shortDescription: {
-            text: "Missing Post-CPI Account Reload"
-        },
-        fullDescription: {
-            text: "Account state accessed after a CPI mutation without reload, which may read or write stale cache state."
-        },
-        helpUri: "https://github.com/akxh5/Solana-EPIC/blob/main/docs/rules/EPIC-SEC-003.md",
-        properties: {
-            category: "Security",
-            precision: "high"
-        }
-    });
-    rulesMap.set("EPIC-SEC-004", {
-        id: "EPIC-SEC-004",
-        shortDescription: {
-            text: "PDA Cryptographic Seed Collision Risk"
-        },
-        fullDescription: {
-            text: "Adjacent variable-length seeds without separation delimiters create boundary ambiguities that permit PDA hijacking."
-        },
-        helpUri: "https://github.com/akxh5/Solana-EPIC/blob/main/docs/rules/EPIC-SEC-004.md",
-        properties: {
-            category: "Security",
-            precision: "high"
-        }
-    });
-    rulesMap.set("EPIC-SEC-005", {
-        id: "EPIC-SEC-005",
-        shortDescription: {
-            text: "Arbitrary CPI Target Program Spoofing"
-        },
-        fullDescription: {
-            text: "Invoking CPI on an external program without verifying that the target program matches a trusted program ID."
-        },
-        helpUri: "https://github.com/akxh5/Solana-EPIC/blob/main/docs/rules/EPIC-SEC-005.md",
-        properties: {
-            category: "Security",
-            precision: "high"
-        }
-    });
-    const results = findings.map((f) => {
-        let level = "warning";
-        const sev = f.severity.toLowerCase();
-        if (sev === "critical" || sev === "high") {
-            level = "error";
-        }
-        else if (sev === "medium") {
-            level = "warning";
+program
+    .command("doctor")
+    .description("Run diagnostics on the environment")
+    .action(() => {
+    const opts = program.opts();
+    const startupShown = printStartup("Environment Diagnostics", !opts.banner);
+    if (!startupShown) {
+        console.log(colors.gray(DIVIDER));
+        console.log(colors.bold(colors.white("Environment Diagnostics")));
+        console.log(colors.gray(DIVIDER));
+        console.log("");
+    }
+    let hasErrors = false;
+    const checkVersion = (cmd, name, required) => {
+        try {
+            const out = execSync(cmd, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+            const shortVer = out.split("\n")[0].substring(0, 50);
+            console.log(`${colors.success("✓")} ${name.padEnd(10)}: ${colors.dim(shortVer)}`);
+        }
+        catch (e) {
+            if (required) {
+                console.log(`${colors.critical("✖")} ${name.padEnd(10)}: ${colors.critical("Not found (Required)")}`);
+                hasErrors = true;
+            }
+            else {
+                console.log(`${colors.warning("⚠️")} ${name.padEnd(10)}: ${colors.dim("Not found (Optional)")}`);
+            }
         }
-        else if (sev === "warning" || sev === "low") {
-            level = "note";
+    };
+    checkVersion("rustc --version", "Rust", true);
+    checkVersion("cargo --version", "Cargo", true);
+    checkVersion("node --version", "Node.js", true);
+    checkVersion("solana --version", "Solana", false);
+    checkVersion("anchor --version", "Anchor", false);
+    console.log("");
+    try {
+        const binaryPath = resolveParserBinary();
+        fs.accessSync(binaryPath, fs.constants.X_OK);
+        console.log(`${colors.success("✓")} parser-v2 : ${colors.dim(binaryPath)}`);
+    }
+    catch (e) {
+        console.log(`${colors.critical("✖")} parser-v2 : ${colors.critical("Binary not found or not executable")}`);
+        hasErrors = true;
+    }
+    const hasAnchor = fs.existsSync(path.join(process.cwd(), "Anchor.toml"));
+    const hasCargo = fs.existsSync(path.join(process.cwd(), "Cargo.toml"));
+    if (hasAnchor) {
+        console.log(`${colors.success("✓")} Workspace : ${colors.dim("Anchor Workspace detected")}`);
+    }
+    else if (hasCargo) {
+        console.log(`${colors.success("✓")} Workspace : ${colors.dim("Cargo Workspace detected")}`);
+    }
+    else {
+        console.log(`${colors.warning("⚠️")} Workspace : ${colors.warning("No Anchor.toml or Cargo.toml found in current directory")}`);
+    }
+    const hasEpicToml = fs.existsSync(path.join(process.cwd(), "epic.toml"));
+    if (hasEpicToml) {
+        try {
+            config.loadEpicConfig();
+            console.log(`${colors.success("✓")} Config    : ${colors.dim("Loaded epic.toml successfully")}`);
         }
-        const relFile = path.relative(process.cwd(), f.location.file);
-        return {
-            ruleId: f.rule_id,
-            ruleIndex: 0,
-            level,
-            message: {
-                text: f.message
-            },
-            locations: [
-                {
-                    physicalLocation: {
-                        artifactLocation: {
-                            uri: relFile,
-                            uriBaseId: "%SRCROOT%"
-                        },
-                        region: {
-                            startLine: f.location.line,
-                            startColumn: f.location.column || 1
-                        }
-                    }
-                }
-            ]
-        };
-    });
-    const rules = Array.from(rulesMap.values());
-    for (const f of findings) {
-        if (!rulesMap.has(f.rule_id)) {
-            const genericRule = {
-                id: f.rule_id,
-                shortDescription: {
-                    text: f.rule_id
-                },
-                fullDescription: {
-                    text: f.message
-                }
-            };
-            rulesMap.set(f.rule_id, genericRule);
-            rules.push(genericRule);
+        catch (e) {
+            console.log(`${colors.critical("✖")} Config    : ${colors.critical("Invalid epic.toml: " + e.message)}`);
+            hasErrors = true;
         }
     }
-    return {
-        $schema: "https://schemastore.azurewebsites.net/schemas/json/sarif-2.1.0-rtm.5.json",
-        version: "2.1.0",
-        runs: [
-            {
-                tool: {
-                    driver: {
-                        name: "EPIC",
-                        informationUri: "https://github.com/akxh5/Solana-EPIC",
-                        version: "0.4.0",
-                        rules
-                    }
-                },
-                results
-            }
-        ]
-    };
-}
+    else {
+        console.log(`${colors.success("✓")} Config    : ${colors.dim("Using default configuration")}`);
+    }
+    const ruleCount = Object.keys(ruleKnowledge).length;
+    console.log(`${colors.success("✓")} Rules     : ${colors.dim(`${ruleCount} safety rules loaded`)}`);
+    console.log("");
+    if (hasErrors) {
+        console.log(colors.critical("Diagnostics failed. EPIC may not function correctly."));
+        process.exit(1);
+    }
+    else {
+        console.log(colors.success("Ready for Audit"));
+        process.exit(0);
+    }
+});
+program
+    .command("explain <rule_id>")
+    .description("Explain a security rule in detail")
+    .action((ruleId) => {
+    const opts = program.opts();
+    printStartup("Rule Explanation", !opts.banner);
+    const knowledge = ruleKnowledge[ruleId];
+    if (!knowledge) {
+        console.log(colors.critical(`Rule ${ruleId} not found.`));
+        console.log(colors.dim("Run 'epic rules' to list all available rules."));
+        process.exit(1);
+    }
+    const band = bandForScore(knowledge.score);
+    console.log(colors.gray(DIVIDER));
+    console.log("");
+    console.log(`${severityBadge(band)}  ${colors.white(ruleId)}  ${colors.gray("·")}  ${colors.white(knowledge.desc)}`);
+    console.log("");
+    console.log(`${colors.dim("Risk Score")}   ${scoreBar(knowledge.score)}  ${colors.white(`${knowledge.score} / 100`)}`);
+    console.log("");
+    console.log(colors.gray(DIVIDER));
+    console.log("");
+    console.log(colors.bold(colors.white("WHY IT'S DANGEROUS")));
+    console.log(colors.dim(knowledge.why));
+    console.log("");
+    console.log(colors.bold(colors.white("WHAT BREAKS")));
+    console.log(colors.warning(knowledge.impact));
+    console.log("");
+    console.log(colors.bold(colors.white("HOW TO FIX")));
+    console.log(colors.green(knowledge.fix));
+    console.log("");
+    console.log(colors.bold(colors.white("HISTORICAL EXPLOITS")));
+    console.log(colors.dim(knowledge.historical));
+    console.log("");
+    console.log(colors.gray(DIVIDER));
+    console.log("");
+});
 program
-    .command("audit")
+    .command("audit [path]")
     .description("Run security rules against the repository.")
-    .argument("[path]", "Path to search and audit", ".")
-    .option("-f, --format <format>", "Output format: text, json, sarif", "text")
+    .option("-f, --format <format>", "Output format: text, json, sarif, markdown", "text")
     .option("-s, --strict", "Exit code 1 if findings severity >= threshold", false)
     .option("-c, --config <path>", "Path to epic.toml configuration file")
+    .option("-v, --verbose", "Show all findings without summarizing")
+    .option("--include-tests", "Include test and fixture directories")
+    .option("--include-fixtures", "Include fixture directories")
+    .option("--all", "Do not ignore any directories")
     .option("--ignore <rules>", "Rule IDs to ignore (comma-separated)", (val) => val.split(",").map(r => r.trim()))
-    .action(async (targetPath, options) => {
+    .action(async (targetPath = ".", options) => {
     const startTime = Date.now();
     try {
         const opts = program.opts();
-        if (options.format === "text") {
-            printBanner(!opts.banner);
-            printInitSequence([
-                "Rust AST Engine Ready",
-                "5 Security Rules Loaded",
-                "Anchor Workspace Detected"
-            ]);
-        }
+        if (options.format === "text")
+            printStartup("Security Audit", !opts.banner);
         const binary = findRustBinary();
         const resolvedPath = path.resolve(targetPath);
+        const auditStart = Date.now();
         const result = spawnSync(binary, ["audit", resolvedPath], { encoding: "utf-8" });
-        if (result.error) {
-            throw new Error(`Failed to execute parser-v2 binary: ${result.error.message}`);
-        }
-        if (result.status !== 0) {
-            console.error(result.stderr || `Execution failed with status code ${result.status}`);
-            process.exit(result.status ?? 1);
-        }
+        const ruleEngineMs = Date.now() - auditStart;
+        if (result.status !== 0)
+            throw new Error("Parser failed");
         const findings = JSON.parse(result.stdout.trim());
-        let epicConfig;
-        try {
-            epicConfig = config.loadEpicConfig(options.config);
-        }
-        catch (err) {
-            epicConfig = config.getDefaultConfig();
-        }
-        const ignoredRules = new Set();
-        if (epicConfig.ignore) {
-            for (const r of epicConfig.ignore) {
-                ignoredRules.add(r.trim());
+        let epicConfig = config.loadEpicConfig(options.config);
+        const ignoredRules = new Set([...(epicConfig.ignore || []), ...(options.ignore || [])]);
+        const builtinIgnore = [".git", "target", "node_modules", "vendor"];
+        if (!options.all) {
+            if (!options.includeTests)
+                builtinIgnore.push("test", "tests", "test-repos");
+            if (!options.includeFixtures)
+                builtinIgnore.push("fixtures", "demo", "examples");
+        }
+        const activeFindings = findings.filter((f) => {
+            if (ignoredRules.has(f.rule_id))
+                return false;
+            const relPath = path.relative(process.cwd(), f.location.file);
+            return !builtinIgnore.some(p => relPath.includes(`/${p}/`) || relPath.startsWith(`${p}/`) || relPath === p);
+        });
+        if (options.format === "text") {
+            // Real repository structure from the parser's analyze pass + filesystem.
+            const fileCount = countRustFiles(resolvedPath);
+            let structsFound = 0, enumsFound = 0, accountsFound = 0;
+            let analyzeMs = 0;
+            try {
+                const analyzeStart = Date.now();
+                const analyzeResult = spawnSync(binary, [resolvedPath], { encoding: "utf-8" });
+                analyzeMs = Date.now() - analyzeStart;
+                if (analyzeResult.status === 0 && analyzeResult.stdout) {
+                    const overview = JSON.parse(analyzeResult.stdout.trim());
+                    structsFound = overview.structs_found ?? 0;
+                    enumsFound = overview.enums_found ?? 0;
+                    accountsFound = Array.isArray(overview.accounts) ? overview.accounts.length : 0;
+                }
             }
-        }
-        if (options.ignore) {
-            const cliIgnores = Array.isArray(options.ignore) ? options.ignore : [options.ignore];
-            for (const r of cliIgnores) {
-                ignoredRules.add(r.trim());
+            catch {
+                // Analyze enrichment is best-effort; the audit result is authoritative.
             }
-        }
-        const activeFindings = findings.filter((f) => !ignoredRules.has(f.rule_id));
-        if (options.format === "text") {
+            const totalTimeMs = Date.now() - startTime;
+            printInitSequence([
+                `Scanning Files\n${colors.cyan("█████████████████████████")} ${colors.dim(`${fileCount} / ${fileCount}`)}`,
+                `Building AST\n${colors.cyan("█████████████████████████")} ${colors.dim("100%")}`,
+                `Running Security Rules\n${colors.cyan("█████████████████████████")} ${colors.dim("100%")}`
+            ]);
+            console.log("");
+            const projName = path.basename(resolvedPath) || ".";
             printSection("Workspace", {
-                Project: path.basename(resolvedPath) || ".",
-                "Security Rules": 5,
+                "Project": projName,
+                "Rules Loaded": Object.keys(ruleKnowledge).length,
                 "Configuration": options.config || "epic.toml"
             });
-            printInitSequence([
-                "Workspace Scanned",
-                "Account Layout Analysis Complete",
-                "Upgrade Safety Verified",
-                "Security Rules Executed"
-            ]);
+            printSection("Repository Overview", {
+                "Rust Files": fileCount,
+                "Structs": structsFound,
+                "Enums": enumsFound,
+                "State Accounts": accountsFound
+            });
             const criticalCount = activeFindings.filter((f) => getSeverityLevel(f.severity) === 3).length;
             const warningCount = activeFindings.filter((f) => getSeverityLevel(f.severity) < 3).length;
-            printSection("Scan Summary", {
-                "Rules Executed": 5,
-                "Findings": activeFindings.length
+            const rulesTriggered = new Set(activeFindings.map((f) => f.rule_id)).size;
+            printSection("Execution Metrics", {
+                "Indexed Files": fileCount,
+                "Parse + AST": `${Math.max(1, analyzeMs)} ms`,
+                "Rule Engine": `${Math.max(1, ruleEngineMs)} ms`,
+                "Total": `${(totalTimeMs / 1000).toFixed(2)} s`
             });
-            for (const finding of activeFindings) {
-                const relPath = path.relative(process.cwd(), finding.location.file);
-                printRuleFinding({
-                    severity: finding.severity,
-                    rule_id: finding.rule_id,
-                    rule_name: finding.rule_name,
-                    location: {
-                        file: relPath,
-                        line: finding.location.line,
-                    },
-                    message: finding.message
+            printSection("Security Summary", {
+                "Critical": criticalCount,
+                "High": warningCount,
+                "Rules Triggered": rulesTriggered
+            });
+            if (options.verbose) {
+                activeFindings.forEach((f) => printRuleFinding(f));
+            }
+            else {
+                const grouped = {};
+                activeFindings.forEach((f) => {
+                    if (!grouped[f.rule_id])
+                        grouped[f.rule_id] = { occurrences: 0, files: new Set(), name: f.rule_name || f.rule_id };
+                    grouped[f.rule_id].occurrences++;
+                    grouped[f.rule_id].files.add(f.location.file);
                 });
+                for (const [id, s] of Object.entries(grouped)) {
+                    console.log(colors.gray(DIVIDER));
+                    console.log(colors.violet(id));
+                    console.log(colors.bold(colors.white(s.name)));
+                    console.log("");
+                    console.log(colors.dim("Occurrences: ") + colors.white(s.occurrences));
+                    console.log(colors.dim("Files: ") + colors.white(s.files.size));
+                    console.log("");
+                }
+                if (activeFindings.length > 0) {
+                    console.log(colors.gray(DIVIDER));
+                    console.log("");
+                }
             }
-            console.log(colors.graphite(DIVIDER));
-            if (activeFindings.length === 0) {
-                console.log(colors.success("No critical vulnerabilities detected."));
+            let mostCommonRule = null;
+            let highestOccurrences = 0;
+            const occurrenceMap = {};
+            for (const finding of activeFindings) {
+                occurrenceMap[finding.rule_id] = (occurrenceMap[finding.rule_id] || 0) + 1;
+                if (occurrenceMap[finding.rule_id] > highestOccurrences) {
+                    highestOccurrences = occurrenceMap[finding.rule_id];
+                    mostCommonRule = finding.rule_id;
+                }
             }
-            else {
-                console.log(colors.success("Completed successfully."));
-                console.log(`${"Rules Executed".padEnd(19)} 5`);
-                console.log(`${"Critical Findings".padEnd(19)} ${criticalCount}`);
-                console.log(`${"Warnings".padEnd(19)} ${warningCount}`);
+            if (mostCommonRule && ruleKnowledge[mostCommonRule]) {
+                const knowledge = ruleKnowledge[mostCommonRule];
+                console.log(colors.bold(colors.white("Most Common Issue")));
+                console.log(colors.dim(`${knowledge.desc}`));
+                console.log(colors.cyan(`${highestOccurrences} occurrence${highestOccurrences === 1 ? "" : "s"}`));
+                console.log("");
+                console.log(colors.dim("Priority"));
+                console.log(colors.white(`Resolve this rule first — it accounts for the most findings.`));
+                console.log("");
             }
-            console.log(`Completed in ${Date.now() - startTime} ms\n`);
-            printFinalSignature();
+            printEndSummary(projName, 5, criticalCount, warningCount, Date.now() - startTime);
         }
         else if (options.format === "json") {
             console.log(JSON.stringify(activeFindings, null, 2));
         }
         else if (options.format === "sarif") {
-            const sarif = generateSarif(activeFindings);
-            const sarifString = JSON.stringify(sarif, null, 2);
-            fs.writeFileSync("sarif.json", sarifString, "utf8");
-            console.log(sarifString);
+            console.log(JSON.stringify(generateSarif(activeFindings), null, 2));
+        }
+        else if (options.format === "markdown") {
+            console.log(generateMarkdown(activeFindings, {
+                project: path.basename(resolvedPath) || ".",
+                scanMs: Date.now() - startTime
+            }));
         }
         if (options.strict) {
             const threshold = epicConfig.failOnSeverity || "CRITICAL";
@@ -428,273 +521,57 @@ program
     .command("rules")
     .description("List all available security rules.")
     .action(() => {
-    console.log("EPIC-SEC-001");
-    console.log("Owner Validation");
-    console.log("Critical");
-    console.log("Implemented\n");
-    console.log("EPIC-SEC-002");
-    console.log("Missing Signer Validation");
-    console.log("Critical");
-    console.log("Implemented\n");
-    console.log("EPIC-SEC-003");
-    console.log("Missing Post-CPI Account Reload");
-    console.log("Critical");
-    console.log("Implemented\n");
-    console.log("EPIC-SEC-004");
-    console.log("PDA Cryptographic Seed Collision Risk");
-    console.log("High");
-    console.log("Implemented\n");
-    console.log("EPIC-SEC-005");
-    console.log("Arbitrary CPI Target Program Spoofing");
-    console.log("Critical");
-    console.log("Implemented");
-});
-program
-    .command("explain")
-    .description("Explain a security rule in detail.")
-    .argument("<rule_id>", "Rule ID to explain")
-    .action(async (ruleId) => {
-    const normRuleId = ruleId.trim().toUpperCase();
-    if (normRuleId === "EPIC-SEC-001") {
-        let content = "";
-        try {
-            const docPaths = [
-                path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../docs/rules/EPIC-SEC-001.md"),
-                path.resolve(process.cwd(), "docs/rules/EPIC-SEC-001.md")
-            ];
-            for (const p of docPaths) {
-                if (fs.existsSync(p)) {
-                    content = fs.readFileSync(p, "utf8");
-                    break;
-                }
-            }
-        }
-        catch (err) {
-            // ignore error
-        }
-        if (content) {
-            console.log(content);
-        }
-        else {
-            console.log(`# EPIC-SEC-001: Owner Validation
-
-## Description
-Tracks mutable account write operations to ensure they are protected by an ownership check (\`account.owner == program_id\`) that dominates the write path.
-
-## Threat Model
-In Solana, any account can be passed to an instruction. If a program writes data to a mutable account without verifying that the account is owned by the program itself, an attacker can pass a forged account with malicious data.
-
-## Vulnerable Example
-\`\`\`rust
-pub fn withdraw(ctx: Context<Withdraw>, amount: u64) -> Result<()> {
-    let vault = &mut ctx.accounts.vault;
-    let mut vault_data = vault.try_borrow_mut_data()?;
-    vault_data[0] = 9;
-    Ok(())
-}
-\`\`\`
-
-## Safe Example
-\`\`\`rust
-#[derive(Accounts)]
-pub struct Withdraw<'info> {
-    #[account(mut)]
-    pub vault: Account<'info, VaultState>,
-}
-\`\`\`
-
-## Historical Exploit References
-* Cashio App ($52M, March 2022)`);
-        }
-    }
-    else if (normRuleId === "EPIC-SEC-002") {
-        let content = "";
-        try {
-            const docPaths = [
-                path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../docs/rules/EPIC-SEC-002.md"),
-                path.resolve(process.cwd(), "docs/rules/EPIC-SEC-002.md")
-            ];
-            for (const p of docPaths) {
-                if (fs.existsSync(p)) {
-                    content = fs.readFileSync(p, "utf8");
-                    break;
-                }
-            }
-        }
-        catch (err) {
-            // ignore error
-        }
-        if (content) {
-            console.log(content);
-        }
-        else {
-            console.log(`# EPIC-SEC-002: Missing Signer Validation
-
-## Description
-Detects situations where authority-like accounts are capable of mutating state, authorizing actions, or executing privileged flows without proving signer authority.
-
-## Threat Model
-In Solana, callers supply all account inputs. Because any caller can pass arbitrary public keys, the program must verify that the authority-like account signed the transaction. Failing to perform this signer validation allows an attacker to spoof the authority account.
-
-## Vulnerable Example
-\`\`\`rust
-pub fn update_config(ctx: Context<UpdateConfig>, new_val: u64) -> Result<()> {
-    ctx.accounts.config.admin_value = new_val;
-    Ok(())
-}
-// with authority declared as AccountInfo without Signer constraint
-\`\`\`
-
-## Safe Example
-\`\`\`rust
-pub fn update_config(ctx: Context<UpdateConfig>, new_val: u64) -> Result<()> {
-    require!(ctx.accounts.authority.is_signer, ErrorCode::MissingSignature);
-    ctx.accounts.config.admin_value = new_val;
-    Ok(())
-}
-\`\`\``);
-        }
+    const opts = program.opts();
+    const startupShown = printStartup("Security Rules", !opts.banner);
+    const rules = [
+        ["EPIC-SEC-001", "Owner Validation"],
+        ["EPIC-SEC-002", "Missing Signer Validation"],
+        ["EPIC-SEC-003", "Missing Post-CPI Account Reload"],
+        ["EPIC-SEC-004", "PDA Cryptographic Seed Collision Risk"],
+        ["EPIC-SEC-005", "Arbitrary CPI Target Program Spoofing"]
+    ];
+    if (!startupShown) {
+        console.log(colors.gray(DIVIDER));
+        console.log(colors.white(colors.bold("EPIC Security Rules")));
+        console.log(colors.gray(DIVIDER));
+        console.log("");
     }
-    else if (normRuleId === "EPIC-SEC-003") {
-        let content = "";
-        try {
-            const docPaths = [
-                path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../docs/rules/EPIC-SEC-003.md"),
-                path.resolve(process.cwd(), "docs/rules/EPIC-SEC-003.md")
-            ];
-            for (const p of docPaths) {
-                if (fs.existsSync(p)) {
-                    content = fs.readFileSync(p, "utf8");
-                    break;
-                }
-            }
-        }
-        catch (err) {
-            // ignore error
-        }
-        if (content) {
-            console.log(content);
+    for (const [id, name] of rules) {
+        const kb = ruleKnowledge[id];
+        const score = kb ? kb.score : 50;
+        const band = bandForScore(score);
+        console.log(`${severityBadge(band)}  ${colors.white(id)}  ${colors.gray("·")}  ${colors.white(name)}`);
+        if (kb) {
+            console.log(`   ${scoreBar(score, 16)}  ${colors.dim(`${score} / 100`)}  ${colors.gray("Implemented")}`);
         }
         else {
-            console.log(`# EPIC-SEC-003: Missing Post-CPI Account Reload
-
-## Description
-Detects scenarios where an account's state data is read or written after a Cross-Program Invocation (CPI) that potentially mutates on-chain state, without executing an intervening reload.
-
-## Threat Model
-In Solana, external programs (like token program or pools) mutate accounts during CPI calls. The local execution context maintains a deserialized in-memory cache of accounts. Calling programs must refresh this cache via \`reload()\` before accessing fields again.
-
-## Vulnerable Example
-\`\`\`rust
-token::transfer(cpi_ctx, amount)?;
-ctx.accounts.vault.amount -= amount; // Stale layout read and write!
-\`\`\`
-
-## Safe Example
-\`\`\`rust
-token::transfer(cpi_ctx, amount)?;
-ctx.accounts.vault.reload()?; // Safe: reload matches state
-ctx.accounts.vault.amount -= amount;
-\`\`\``);
+            console.log(`   ${colors.gray("Implemented")}`);
         }
+        console.log("");
     }
-    else if (normRuleId === "EPIC-SEC-004") {
-        let content = "";
-        try {
-            const docPaths = [
-                path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../docs/rules/EPIC-SEC-004.md"),
-                path.resolve(process.cwd(), "docs/rules/EPIC-SEC-004.md")
-            ];
-            for (const p of docPaths) {
-                if (fs.existsSync(p)) {
-                    content = fs.readFileSync(p, "utf8");
-                    break;
-                }
-            }
-        }
-        catch (err) {
-            // ignore error
-        }
-        if (content) {
-            console.log(content);
-        }
-        else {
-            console.log(`# EPIC-SEC-004: PDA Cryptographic Seed Collision Risk
-
-## Description
-Detects scenarios where adjacent variable-length seeds in Program Derived Address (PDA) derivation can merge boundaries, allowing an attacker to generate the same address from two different inputs.
-
-## Threat Model
-In Solana, PDAs are derived by concatenating the raw seed bytes without adding delimiters. When two variable-length seeds (like strings or dynamic byte arrays) are placed next to each other, boundary bytes can shift between seeds while keeping the concatenated byte stream identical.
-
-## Vulnerable Example
-\`\`\`rust
-Pubkey::find_program_address(
-    &[
-        user_name.as_bytes(),
-        folder_name.as_bytes(),
-    ],
-    program_id,
-);
-\`\`\`
-
-## Safe Example
-\`\`\`rust
-Pubkey::find_program_address(
-    &[
-        user_name.as_bytes(),
-        b"|",
-        folder_name.as_bytes(),
-    ],
-    program_id,
-);
-\`\`\``);
-        }
-    }
-    else if (normRuleId === "EPIC-SEC-005") {
-        let content = "";
-        try {
-            const docPaths = [
-                path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../../docs/rules/EPIC-SEC-005.md"),
-                path.resolve(process.cwd(), "docs/rules/EPIC-SEC-005.md")
-            ];
-            for (const p of docPaths) {
-                if (fs.existsSync(p)) {
-                    content = fs.readFileSync(p, "utf8");
-                    break;
-                }
-            }
-        }
-        catch (err) {
-            // ignore error
-        }
-        if (content) {
-            console.log(content);
-        }
-        else {
-            console.log(`# EPIC-SEC-005: Arbitrary CPI Target Program Spoofing
-
-## Description
-Detects scenarios where a program invokes another program via CPI without verifying that the target program matches a trusted program ID.
-
-## Threat Model
-In Solana, callers supply all input accounts, including the program being invoked. If the program fails to verify that the target program account is trusted, an attacker can pass a custom malicious program and hijack control flow under the PDA authority of the program.
-
-## Vulnerable Example
-\`\`\`rust
-invoke(&ix, &[source, dest, token_program])?; // token_program is not validated!
-\`\`\`
+    console.log(colors.dim("Run 'epic explain <RULE-ID>' for a full breakdown of any rule."));
+    console.log("");
+});
+program.configureHelp({
+    formatHelp: (cmd, helper) => {
+        const noBannerFlag = !!cmd.opts().noBanner || process.argv.includes("--no-banner");
+        const header = getBannerString(noBannerFlag);
+        return `${header}
+${colors.bold("Commands")}
+  ${colors.white("audit".padEnd(14))} Run security rules against the repository.
+  ${colors.white("doctor".padEnd(14))} Run diagnostics on the environment.
+  ${colors.white("explain".padEnd(14))} Explain a security rule in detail.
+  ${colors.white("rules".padEnd(14))} List all available security rules.
+  ${colors.white("analyze".padEnd(14))} Analyze a Solana program workspace.
+  ${colors.white("check".padEnd(14))} Compare two workspace versions.
 
-## Safe Example
-\`\`\`rust
-require_keys_eq!(token_program.key(), token::ID);
-invoke(&ix, &[source, dest, token_program])?;
-\`\`\``);
-        }
-    }
-    else {
-        console.log(`Rule ${ruleId} not found.`);
-        process.exit(1);
+${colors.bold("Flags")}
+  ${colors.white("-v, --verbose".padEnd(16))} Show all findings instead of grouping
+  ${colors.white("--include-tests".padEnd(16))} Include test directories in scan
+  ${colors.white("-f, --format".padEnd(16))} Output format: text, json, sarif, markdown
+  ${colors.white("--no-banner".padEnd(16))} Disable the startup banner
+  ${colors.white("-h, --help".padEnd(16))} Print help
+`;
     }
 });
 program.parse(process.argv);