audit-notes-cli 0.1.5 → 0.1.6

package/dist/cli.js

@@ -6,6 +6,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
+/* ===================== INTERNAL ===================== */
 const license_1 = require("./license");
 const slither_1 = require("./analyzer/slither");
 const detectors_1 = require("./analyzer/detectors");
@@ -13,9 +14,12 @@ const normalize_1 = require("./analyzer/normalize");
 const compare_1 = require("./diff/compare");
 const markdown_1 = require("./report/markdown");
 const sarif_1 = require("./report/sarif");
+const summarize_1 = require("./report/summarize");
 const profiles_1 = require("./profiles/profiles");
 const recommendations_1 = require("./paid/recommendations");
 const fixHints_1 = require("./paid/fixHints");
+const comment_1 = require("./github/comment");
+const checks_1 = require("./github/checks");
 /* ===================== VERSION ===================== */
 const pkg = JSON.parse(fs_1.default.readFileSync(path_1.default.join(__dirname, "../package.json"), "utf8"));
 const VERSION = pkg.version;
@@ -40,7 +44,48 @@ function getProfile() {
     }
     return p;
 }
-/* ===================== CORE ===================== */
+/* ===================== LOAD REPORT ===================== */
+function loadReport() {
+    const p = path_1.default.resolve("output/AUDIT_NOTES.json");
+    if (!fs_1.default.existsSync(p)) {
+        throw new Error("AUDIT_NOTES.json not found. Run `audit-notes run` first.");
+    }
+    return JSON.parse(fs_1.default.readFileSync(p, "utf8"));
+}
+/* ===================== EXPLAIN ===================== */
+function explainFinding(id) {
+    const report = loadReport();
+    const finding = report.findings.find((f) => f.id === id);
+    if (!finding) {
+        throw new Error(`Finding ${id} not found`);
+    }
+    console.log(`
+Finding ID: ${finding.id}
+Severity:   ${finding.impact}
+Detector:   ${finding.check}
+
+Description:
+${finding.description}
+`);
+    // Optional PRO guidance
+    try {
+        (0, license_1.validateLicense)();
+        const rec = (0, recommendations_1.generateRecommendations)([finding])[0];
+        if (rec) {
+            console.log("\nRecommendation:");
+            console.log(rec.text);
+        }
+        const fix = (0, fixHints_1.generateFixHints)([finding])[0];
+        if (fix) {
+            console.log("\nFix Hint:");
+            console.log(fix.explanation);
+        }
+    }
+    catch {
+        /* Free users – silent */
+    }
+}
+/* ===================== CORE RUN ===================== */
 async function run() {
     if (wantRecommendations || wantFixHints) {
         (0, license_1.validateLicense)();
@@ -53,33 +98,53 @@ async function run() {
     const raw = (0, detectors_1.analyzeDetectors)((0, slither_1.loadSlither)(slitherPath).detectors);
     const current = (0, profiles_1.applyProfile)((0, normalize_1.normalizeDetectors)(raw), profile);
     fs_1.default.mkdirSync("output", { recursive: true });
-    if (useSarif) {
-        fs_1.default.writeFileSync("output/audit-notes.sarif", JSON.stringify((0, sarif_1.generateSarif)(current), null, 2));
-        return;
-    }
-    let markdown;
+    /* ---------- Stable machine output ---------- */
+    fs_1.default.writeFileSync("output/AUDIT_NOTES.json", JSON.stringify({
+        schemaVersion: "1.0",
+        version: VERSION,
+        findings: current
+    }, null, 2));
+    let diff = undefined;
+    /* ---------- Diff + CI gating ---------- */
     if (useDiff) {
         const basePath = getFlag("--base");
         if (!basePath)
             throw new Error("Diff requires --base");
         const baseRaw = (0, detectors_1.analyzeDetectors)((0, slither_1.loadSlither)(basePath).detectors);
         const base = (0, profiles_1.applyProfile)((0, normalize_1.normalizeDetectors)(baseRaw), profile);
-        const diff = (0, compare_1.diffFindings)(base, current);
+        diff = (0, compare_1.diffFindings)(base, current);
         const blocking = diff.added.filter((f) => f.impact === "HIGH" || f.impact === "CRITICAL");
+        if (process.env.GITHUB_ACTIONS) {
+            await (0, checks_1.createCheckRun)(blocking.length ? "failure" : "success", blocking.length
+                ? `❌ ${blocking.length} new HIGH/CRITICAL issues`
+                : "✅ No new HIGH/CRITICAL issues");
+        }
         if (blocking.length)
             process.exit(2);
-        markdown = (0, markdown_1.generateMarkdown)({ findings: current, diff });
     }
-    else {
-        markdown = (0, markdown_1.generateMarkdown)({ findings: current });
+    /* ---------- Output formats ---------- */
+    const format = getFlag("--format") ?? "md";
+    if (format === "json")
+        return;
+    if (format === "summary") {
+        fs_1.default.writeFileSync("output/SUMMARY.md", (0, summarize_1.generateSummary)({ findings: current, diff }));
+        return;
+    }
+    if (useSarif) {
+        fs_1.default.writeFileSync("output/audit-notes.sarif", JSON.stringify((0, sarif_1.generateSarif)(current), null, 2));
+        return;
     }
-    fs_1.default.writeFileSync("output/AUDIT_NOTES.md", markdown);
+    fs_1.default.writeFileSync("output/AUDIT_NOTES.md", (0, markdown_1.generateMarkdown)({ findings: current, diff }));
     if (wantRecommendations) {
         fs_1.default.writeFileSync("output/recommendations.json", JSON.stringify((0, recommendations_1.generateRecommendations)(current), null, 2));
     }
     if (wantFixHints) {
         fs_1.default.writeFileSync("output/fix-hints.json", JSON.stringify((0, fixHints_1.generateFixHints)(current), null, 2));
     }
+    if (cmd === "comment") {
+        const summary = (0, summarize_1.generateSummary)({ findings: current, diff });
+        await (0, comment_1.upsertPRComment)(summary);
+    }
 }
 /* ===================== ENTRY ===================== */
 async function main() {
@@ -87,14 +152,13 @@ async function main() {
         console.log(`audit-notes v${VERSION}`);
         return;
     }
-    if (cmd === "run") {
-        await run();
-    }
-    else if (cmd === "check") {
-        (0, license_1.validateLicense)();
-    }
-    else {
-        console.log(`audit-notes v${VERSION}`);
+    if (cmd === "explain") {
+        const id = args[1];
+        if (!id)
+            throw new Error("Usage: audit-notes explain <findingId>");
+        explainFinding(id);
+        return;
     }
+    await run();
 }
 main();

package/dist/explain.js

@@ -0,0 +1,33 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.explainFinding = explainFinding;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function explainFinding(id) {
+    const reportPath = path_1.default.resolve("output/AUDIT_NOTES.json");
+    if (!fs_1.default.existsSync(reportPath)) {
+        throw new Error("AUDIT_NOTES.json not found. Run audit-notes first.");
+    }
+    const report = JSON.parse(fs_1.default.readFileSync(reportPath, "utf8"));
+    const finding = report.findings.find((f) => f.id === id);
+    if (!finding) {
+        throw new Error(`Finding ${id} not found`);
+    }
+    console.log(`
+Finding ID: ${finding.id}
+Severity: ${finding.impact}
+Detector: ${finding.detector}
+
+Description:
+${finding.description}
+
+Why it matters:
+${finding.why || "This issue may impact security, maintainability, or gas usage."}
+
+Location:
+${finding.file}:${finding.startLine}
+`);
+}

package/dist/github/checks.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCheckRun = createCheckRun;
+const node_fetch_1 = __importDefault(require("node-fetch"));
+async function createCheckRun(conclusion, summary) {
+    const token = process.env.GITHUB_TOKEN;
+    const repo = process.env.GITHUB_REPOSITORY;
+    const sha = process.env.GITHUB_SHA;
+    const [owner, repoName] = repo.split("/");
+    await (0, node_fetch_1.default)(`https://api.github.com/repos/${owner}/${repoName}/check-runs`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${token}`,
+            "Content-Type": "application/json",
+            Accept: "application/vnd.github+json"
+        },
+        body: JSON.stringify({
+            name: "Audit Notes",
+            head_sha: sha,
+            status: "completed",
+            conclusion,
+            output: {
+                title: "Audit Notes Security Check",
+                summary
+            }
+        })
+    });
+}

package/dist/github/comment.js

@@ -3,18 +3,50 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.postPRComment = postPRComment;
+exports.upsertPRComment = upsertPRComment;
+const fs_1 = __importDefault(require("fs"));
 const node_fetch_1 = __importDefault(require("node-fetch"));
-async function postPRComment(repo, pr, token, body) {
-    const res = await (0, node_fetch_1.default)(`https://api.github.com/repos/${repo}/issues/${pr}/comments`, {
-        method: "POST",
-        headers: {
-            Authorization: `Bearer ${token}`,
-            "Content-Type": "application/json"
-        },
-        body: JSON.stringify({ body })
+const MARKER = "<!-- audit-notes -->";
+function ghHeaders(token) {
+    return {
+        Authorization: `Bearer ${token}`,
+        "Content-Type": "application/json",
+        Accept: "application/vnd.github+json"
+    };
+}
+async function upsertPRComment(body) {
+    if (!process.env.GITHUB_ACTIONS) {
+        throw new Error("Not running in GitHub Actions");
+    }
+    const token = process.env.GITHUB_TOKEN;
+    if (!token)
+        throw new Error("GITHUB_TOKEN not set");
+    const event = JSON.parse(fs_1.default.readFileSync(process.env.GITHUB_EVENT_PATH, "utf8"));
+    const prNumber = event.pull_request?.number;
+    if (!prNumber)
+        throw new Error("Not a PR event");
+    const repo = process.env.GITHUB_REPOSITORY;
+    const baseUrl = `https://api.github.com/repos/${repo}/issues/${prNumber}/comments`;
+    const fullBody = `${body}\n\n${MARKER}`;
+    // 1. Fetch existing comments
+    const res = await (0, node_fetch_1.default)(baseUrl, {
+        headers: ghHeaders(token)
     });
-    if (!res.ok) {
-        throw new Error("Failed to post PR comment");
+    const comments = await res.json();
+    const existing = comments.find((c) => typeof c.body === "string" && c.body.includes(MARKER));
+    // 2. Update or create
+    if (existing) {
+        await (0, node_fetch_1.default)(`https://api.github.com/repos/${repo}/issues/comments/${existing.id}`, {
+            method: "PATCH",
+            headers: ghHeaders(token),
+            body: JSON.stringify({ body: fullBody })
+        });
+    }
+    else {
+        await (0, node_fetch_1.default)(baseUrl, {
+            method: "POST",
+            headers: ghHeaders(token),
+            body: JSON.stringify({ body: fullBody })
+        });
     }
 }

package/dist/paid/fallbacks.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FALLBACK_GUIDANCE = void 0;
+exports.FALLBACK_GUIDANCE = {
+    "unused-state-variable": "This state variable is never accessed. Consider removing it or verifying that related logic is complete.",
+    "low-level-calls": "Low-level calls bypass Solidity safety checks. Ensure return values are validated and failures handled explicitly.",
+    "reentrancy": "External calls before state updates may enable reentrancy. Review execution order carefully.",
+    "dead-code": "This code is never executed. Consider removing it to reduce attack surface and bytecode size."
+};

package/dist/report/markdown.js

@@ -4,6 +4,7 @@ exports.generateMarkdown = generateMarkdown;
 function generateMarkdown(input) {
     var _a;
     let md = `# Smart Contract Audit Notes\n\n`;
+    /* ===================== PR SUMMARY ===================== */
     if (input.diff) {
         const { added, increasedRisk, unchanged } = input.diff;
         md += `## 🔍 Pull Request Risk Summary\n\n`;
@@ -13,26 +14,27 @@ function generateMarkdown(input) {
         else {
             md += `### ❗ New Findings\n\n`;
             for (const f of added) {
-                md += `- **${f.check}** — ${f.impact}\n`;
+                md += `- **${f.check}** (${f.impact}) — \`${f.id.slice(0, 8)}\`\n`;
             }
             md += `\n`;
         }
         if (increasedRisk.length > 0) {
             md += `### 🔺 Risk Increased\n\n`;
             for (const f of increasedRisk) {
-                md += `- **${f.check}** — ${f.impact}\n`;
+                md += `- **${f.check}** (${f.impact}) — \`${f.id.slice(0, 8)}\`\n`;
             }
             md += `\n`;
         }
         if (unchanged.length > 0) {
             md += `### ⚠️ Existing Issues\n\n`;
             for (const f of unchanged) {
-                md += `- ${f.check}\n`;
+                md += `- ${f.check} — \`${f.id.slice(0, 8)}\`\n`;
             }
             md += `\n`;
         }
         md += `---\n\n`;
     }
+    /* ===================== FULL FINDINGS ===================== */
     md += `## Full Findings\n\n`;
     md += `Total findings: **${input.findings.length}**\n\n`;
     const byImpact = {};
@@ -44,7 +46,29 @@ function generateMarkdown(input) {
         md += `## ${impact} Severity\n\n`;
         for (const f of byImpact[impact]) {
             md += `### ${f.check}\n\n`;
+            md += `**Finding ID:** \`${f.id}\`\n\n`;
             md += `${f.description}\n\n`;
+            /* ---------- Locations ---------- */
+            if (f.locations.length > 0) {
+                md += `**Locations:**\n\n`;
+                for (const loc of f.locations) {
+                    let line = `- `;
+                    if (loc.file) {
+                        line += `\`${loc.file}\``;
+                    }
+                    if (loc.contract) {
+                        line += ` • contract \`${loc.contract}\``;
+                    }
+                    if (loc.function) {
+                        line += ` • function \`${loc.function}\``;
+                    }
+                    if (loc.lines && loc.lines.length > 0) {
+                        line += ` • lines ${loc.lines.join(", ")}`;
+                    }
+                    md += `${line}\n`;
+                }
+                md += `\n`;
+            }
             md += `---\n\n`;
         }
     }

package/dist/report/summarize.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSummary = generateSummary;
+function generateSummary(input) {
+    const total = input.findings.length;
+    const byImpact = {
+        CRITICAL: 0,
+        HIGH: 0,
+        MEDIUM: 0,
+        LOW: 0
+    };
+    for (const f of input.findings) {
+        if (byImpact[f.impact] !== undefined) {
+            byImpact[f.impact]++;
+        }
+    }
+    let md = `## 🔐 Audit Notes Summary\n\n`;
+    if (input.diff) {
+        const blockers = input.diff.added.filter(f => f.impact === "HIGH" || f.impact === "CRITICAL");
+        if (blockers.length === 0) {
+            md += `✅ No new HIGH or CRITICAL risks introduced.\n\n`;
+        }
+        else {
+            md += `❌ **New HIGH / CRITICAL risks introduced**\n\n`;
+            for (const f of blockers) {
+                md += `- ${f.check} — ${f.impact} (ID: \`${f.id}\`)\n`;
+            }
+            md += `\nCI blocked until resolved.\n\n`;
+        }
+    }
+    md += `- Total findings: ${total}\n`;
+    md += `- High / Critical: ${byImpact.HIGH + byImpact.CRITICAL}\n`;
+    md += `- Medium: ${byImpact.MEDIUM}\n`;
+    md += `- Low: ${byImpact.LOW}\n\n`;
+    md += `_See \`output/AUDIT_NOTES.md\` for full details._\n`;
+    return md;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "audit-notes-cli",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "type": "commonjs",
   "bin": {
     "audit-notes": "dist/cli.js",