audit-notes-cli 0.1.0 → 0.1.2

package/README.md

@@ -1,41 +1,250 @@
-# AI-Assisted Audit 
-
-Professional **security pre-review tooling** for smart contracts.
-
-This is NOT:
-- an AI auditor
-- a vulnerability scanner
-- severity scoring software
-
-This IS:
-- a thinking assistant for auditors
-- deterministic security analysis
-- structured audit context before full audits
-
----
-
-## What it generates
-- Privileged role map
-- External call & reentrancy surfaces
-- State mutation & invariant hints
-- Upgradeability risks
-- Critical audit questions
-
-Output: `AUDIT_NOTES.md`
-
----
-
-## Why this exists
-Most audit issues are missed due to **lost context**, not missing tools.
-
-This tool extracts structure so humans reason better.
-
----
-
-## Usage (CLI)
-
-```bash
-slither . --json slither.json
-export AUDIT_NOTES_LICENSE=AN-XXXX
-export OPENAI_API_KEY=sk-...
-audit-notes .
+## Audit Notes CLI
+------------------------------------------------------------------------
+Noise-Free Smart Contract Security for PRs
+
+Audit Notes is a CI-first smart contract audit CLI built on top of Slither.
+It focuses on signal over noise by failing CI only when new HIGH or CRITICAL issues are introduced.
+
+The core scan and CI gating are free forever.
+Audit Notes PRO adds actionable remediation guidance.
+
+--------------------------------------------------------------------------
+
+## Why Audit Notes?
+
+Most security tools are noisy.
+
+Audit Notes is opinionated:
+
+- Catch new risks, not old ones
+
+- Fail CI only on HIGH / CRITICAL regressions
+
+- Generate outputs developers can actually read
+
+- Work locally and in CI
+
+- No dashboards. No accounts. Just files.
+
+--------------------------------------------------------------------------
+
+## Features 
+
+#🆓 Free (No license required)
+
+- Static analysis via Slither
+
+- Markdown audit notes
+
+- SARIF output (GitHub Security tab)
+
+- PR diffing against base branch
+
+- CI gating on new HIGH / CRITICAL issues
+
+- Noise suppression profiles
+
+# 💎 PRO (License required)
+
+- Remediation recommendations
+
+- Fix hints and guidance
+
+- Designed for solo auditors and teams
+
+- Works locally and in CI
+
+--------------------------------------------------------------------------
+
+## Installation
+
+Audit Notes is distributed via npm.
+
+- npm install -g audit-notes
+
+
+Or run directly with:
+
+- npx audit-notes
+
+--------------------------------------------------------------------------
+
+## Prerequisites
+
+Audit Notes expects a Slither JSON report.
+
+Generate one with:
+
+- slither . --json slither.json || true
+
+--------------------------------------------------------------------------
+
+## Usage
+
+Run a basic audit (Free)
+
+- npx audit-notes run
+
+Generates:
+
+output/AUDIT_NOTES.md
+
+--------------------------------------------------------------------------
+
+## Generate SARIF (Free)
+
+- npx audit-notes run --sarif
+
+Generates:
+
+output/audit-notes.sarif
+
+Upload this to GitHub’s Security tab using upload-sarif.
+
+--------------------------------------------------------------------------
+
+## PR diff mode (Free, CI-safe)
+
+- npx audit-notes run --diff --base slither-main.json
+
+Behavior:
+
+Compares current findings with base
+
+Fails CI only if new HIGH / CRITICAL issues are introduced
+
+--------------------------------------------------------------------------
+
+## PRO Usage
+
+PRO unlocks guidance on how to fix issues, not basic scanning.
+
+Set your license
+- export AUDIT_NOTES_LICENSE=AN-PRO-XXXX
+- export AUDIT_NOTES_SECRET=your_secret_here
+
+(For local testing, AN-DEV can be used.)
+
+
+## Generate remediation recommendations (PRO)
+
+- npx audit-notes run --recommendations
+
+Generates:
+
+output/recommendations.json
+
+## Generate fix hints (PRO)
+
+- npx audit-notes run --fix-hints
+
+Generates:
+
+output/fix-hints.json
+
+
+- Without a license
+
+Running PRO commands without a license will show:
+
+" This feature requires Audit Notes PRO. Set AUDIT_NOTES_LICENSE to continue."
+
+--------------------------------------------------------------------------
+
+## Free vs PRO
+
+Feature	Free	PRO
+Static analysis (Slither)	✅	✅
+Markdown audit report	✅	✅
+SARIF (GitHub Security tab)	✅	✅
+PR diff & CI gating	✅	✅
+Noise suppression profiles	✅	✅
+Remediation recommendations	❌	✅
+Fix hints & guidance	❌	✅
+Solo usage	✅	✅
+Team / CI usage	✅	✅
+Priority support	❌	✅
+
+Audit Notes is free forever for scanning and CI gating.
+PRO adds actionable guidance.
+
+--------------------------------------------------------------------------
+
+## GitHub Actions
+
+Audit Notes is designed to run in CI.
+
+Typical workflow:
+
+- Run Slither on base branch
+
+- Run Slither on PR
+
+- Run audit-notes run --diff --base slither-main.json
+
+Optionally upload SARIF
+
+--------------------------------------------------------------------------
+
+## Philosophy
+
+Audit Notes is intentionally minimal:
+
+- No dashboards
+
+- No accounts
+
+- No phone-home
+
+- Files you can review, diff, and commit
+
+Security tools should help you think less, not more.
+
+--------------------------------------------------------------------------
+
+## License & Plans
+
+Audit Notes is free to use for scanning and CI gating.
+
+## PRO plans
+
+- PRO Solo — individual auditors
+
+- PRO Team — shared repos and CI
+
+## PRO unlocks:
+
+- Remediation recommendations
+
+- Fix hints
+
+Pricing is simple and transparent.
+
+--------------------------------------------------------------------------
+
+## Roadmap
+
+- Improve recommendation quality
+
+- Better PR summaries
+
+- Optional team-level enforcement (later)
+
+- No bloat. No feature creep.
+
+--------------------------------------------------------------------------
+
+## Contributing
+
+Issues and PRs are welcome.
+
+This project prioritizes clarity, signal, and developer trust.
+
+--------------------------------------------------------------------------
+
+## One-line summary
+
+- Free for scanning and CI gating.
+- PRO for guidance on how to fix what’s found.
+
+--------------------------------------------------------------------------

package/dist/analyzer/diff.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffFindings = diffFindings;
+function fingerprint(f) {
+    const loc = f.locations[0];
+    return [
+        f.check,
+        loc?.contract ?? "",
+        loc?.function ?? ""
+    ].join("|");
+}
+function diffFindings(base, current) {
+    const baseMap = new Map(base.map(f => [fingerprint(f), f]));
+    const currMap = new Map(current.map(f => [fingerprint(f), f]));
+    const added = [];
+    const existing = [];
+    const removed = [];
+    for (const [key, curr] of currMap) {
+        if (baseMap.has(key)) {
+            existing.push(curr);
+        }
+        else {
+            added.push(curr);
+        }
+    }
+    for (const [key, baseF] of baseMap) {
+        if (!currMap.has(key)) {
+            removed.push(baseF);
+        }
+    }
+    return { added, existing, removed };
+}

package/dist/analyzer/normalize.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeDetectors = normalizeDetectors;
+const crypto_1 = __importDefault(require("crypto"));
+function normalizeDetectors(detectors) {
+    return detectors.map((d) => ({
+        id: crypto_1.default
+            .createHash("sha1")
+            .update(d.check + JSON.stringify(d.locations ?? []))
+            .digest("hex"),
+        check: d.check,
+        description: d.description,
+        impact: mapImpact(d.impact),
+        riskScore: mapRiskScore(d.impact),
+        locations: d.locations ?? []
+    }));
+}
+function mapImpact(impact) {
+    switch (impact?.toLowerCase()) {
+        case "critical":
+        case "high":
+            return "HIGH";
+        case "medium":
+            return "MEDIUM";
+        default:
+            return "LOW";
+    }
+}
+function mapRiskScore(impact) {
+    switch (impact?.toLowerCase()) {
+        case "critical":
+            return 9;
+        case "high":
+            return 7;
+        case "medium":
+            return 4;
+        default:
+            return 1;
+    }
+}

package/dist/analyzer/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cli.js

@@ -9,55 +9,79 @@ const path_1 = __importDefault(require("path"));
 const license_1 = require("./license");
 const slither_1 = require("./analyzer/slither");
 const detectors_1 = require("./analyzer/detectors");
+const normalize_1 = require("./analyzer/normalize");
+const compare_1 = require("./diff/compare");
 const markdown_1 = require("./report/markdown");
-const prompt_1 = require("./llm/prompt");
-const client_1 = require("./llm/client");
-const rules_schema_json_1 = __importDefault(require("./rules/rules.schema.json"));
-const cmd = process.argv[2] ?? "run";
+const sarif_1 = require("./report/sarif");
+const profiles_1 = require("./profiles/profiles");
+const recommendations_1 = require("./paid/recommendations");
+const fixHints_1 = require("./paid/fixHints");
+const args = process.argv.slice(2);
+const cmd = args[0] ?? "run";
+const useSarif = args.includes("--sarif");
+const useDiff = args.includes("--diff");
+const wantRecommendations = args.includes("--recommendations");
+const wantFixHints = args.includes("--fix-hints");
+function getFlag(name) {
+    const i = args.indexOf(name);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+function getProfile() {
+    const i = args.indexOf("--profile");
+    if (i === -1)
+        return "default";
+    const p = args[i + 1];
+    if (!["default", "defi", "protocol", "strict"].includes(p)) {
+        throw new Error("Invalid profile");
+    }
+    return p;
+}
 async function run() {
-    (0, license_1.validateLicense)();
+    if (wantRecommendations || wantFixHints) {
+        (0, license_1.validateLicense)();
+    }
     const slitherPath = path_1.default.resolve("slither.json");
     if (!fs_1.default.existsSync(slitherPath)) {
-        throw new Error("slither.json not found. Run `slither <path> --json slither.json` first.");
+        throw new Error("slither.json not found");
+    }
+    const profile = getProfile();
+    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;
     }
-    const slither = (0, slither_1.loadSlither)(slitherPath);
-    const findings = (0, detectors_1.analyzeDetectors)(slither.detectors);
-    let report;
-    if (process.env.OPENAI_API_KEY) {
-        const prompt = (0, prompt_1.buildPrompt)({ findings }, rules_schema_json_1.default);
-        report = await (0, client_1.generateAuditNotes)(prompt);
+    let markdown;
+    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);
+        const blocking = diff.added.filter((f) => f.impact === "HIGH" || f.impact === "CRITICAL");
+        if (blocking.length)
+            process.exit(2);
+        markdown = (0, markdown_1.generateMarkdown)({ findings: current, diff });
     }
     else {
-        report = (0, markdown_1.generateMarkdown)({ findings });
+        markdown = (0, markdown_1.generateMarkdown)({ findings: current });
+    }
+    fs_1.default.writeFileSync("output/AUDIT_NOTES.md", markdown);
+    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));
     }
-    fs_1.default.mkdirSync("output", { recursive: true });
-    fs_1.default.writeFileSync("output/AUDIT_NOTES.md", report);
-    console.log("✅ Audit notes generated → output/AUDIT_NOTES.md");
 }
 async function main() {
-    try {
-        if (cmd === "run") {
-            await run();
-        }
-        else if (cmd === "check") {
-            (0, license_1.validateLicense)();
-            console.log("✅ License valid");
-        }
-        else if (cmd === "version") {
-            console.log("audit-notes v0.1.0");
-        }
-        else {
-            console.log(`
-Usage:
-  audit-notes run
-  audit-notes check
-  audit-notes version
-`);
-        }
-    }
-    catch (err) {
-        console.error("❌", err.message);
-        process.exit(1);
-    }
+    if (cmd === "run")
+        await run();
+    else if (cmd === "check")
+        (0, license_1.validateLicense)();
+    else
+        console.log("audit-notes v0.1.0");
 }
 main();

package/dist/diff/compare.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffFindings = diffFindings;
+const normalize_1 = require("./normalize");
+function diffFindings(base, current) {
+    const baseMap = new Map(base.map((f) => [(0, normalize_1.normalizeFindingKey)(f), f]));
+    const result = {
+        added: [],
+        increasedRisk: [],
+        unchanged: []
+    };
+    for (const f of current) {
+        const key = (0, normalize_1.normalizeFindingKey)(f);
+        const prev = baseMap.get(key);
+        if (!prev) {
+            result.added.push(f);
+        }
+        else if (f.riskScore > prev.riskScore) {
+            result.increasedRisk.push(f);
+        }
+        else {
+            result.unchanged.push(f);
+        }
+    }
+    return result;
+}

package/dist/diff/normalize.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeFindingKey = normalizeFindingKey;
+function normalizeFindingKey(f) {
+    const loc = f.locations[0];
+    return [
+        f.check,
+        loc?.contract ?? "unknown",
+        loc?.function ?? "unknown"
+    ].join("::");
+}

package/dist/diff/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/github/comment.js

@@ -0,0 +1,20 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postPRComment = postPRComment;
+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 })
+    });
+    if (!res.ok) {
+        throw new Error("Failed to post PR comment");
+    }
+}

package/dist/invariants/suggest.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggestInvariants = suggestInvariants;
+function suggestInvariants(findings) {
+    const invariants = [];
+    for (const f of findings) {
+        if (f.riskLevel !== "CRITICAL")
+            continue;
+        if (f.check.toLowerCase().includes("reentrancy")) {
+            invariants.push("State must be updated before any external call execution.");
+        }
+        if (f.check.toLowerCase().includes("delegatecall")) {
+            invariants.push("Delegatecall targets must be immutable and trusted.");
+        }
+        if (f.check.toLowerCase().includes("upgrade")) {
+            invariants.push("Upgrade paths must be restricted to governance-controlled roles.");
+        }
+    }
+    return [...new Set(invariants)];
+}

package/dist/license.js

@@ -1,13 +1,67 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateLicense = validateLicense;
+const crypto_1 = __importDefault(require("crypto"));
+/**
+ * Validate PRO license.
+ * This function MUST ONLY be called for paid features.
+ */
 function validateLicense() {
     const key = process.env.AUDIT_NOTES_LICENSE;
     if (!key) {
-        throw new Error("Missing license key. Set AUDIT_NOTES_LICENSE environment variable.");
+        throw new Error("This feature requires Audit Notes PRO. Set AUDIT_NOTES_LICENSE to continue.");
     }
-    if (key.length < 20 || !key.startsWith("AN-")) {
-        throw new Error("Invalid license key format.");
+    // Explicit dev / CI bypass
+    if (key === "AN-DEV" || key === "AN-CI") {
+        return {
+            plan: "PRO",
+            scope: "SOLO",
+            interval: "M",
+            expiry: "2099-12"
+        };
     }
-    return true;
+    const secret = process.env.AUDIT_NOTES_SECRET;
+    if (!secret) {
+        throw new Error("AUDIT_NOTES_SECRET must be set when using a paid license.");
+    }
+    /**
+     * Expected format:
+     * AN-PRO-SOLO-M-2026-01-<SIG>
+     */
+    const parts = key.split("-");
+    if (parts.length !== 7) {
+        throw new Error("Invalid license key format");
+    }
+    const [prefix, plan, scope, interval, year, month, sig] = parts;
+    if (prefix !== "AN")
+        throw new Error("Invalid license prefix");
+    if (plan !== "PRO")
+        throw new Error("Invalid plan");
+    if (scope !== "SOLO" && scope !== "TEAM") {
+        throw new Error("Invalid license scope");
+    }
+    if (interval !== "M" && interval !== "Y") {
+        throw new Error("Invalid billing interval");
+    }
+    const expiry = `${year}-${month}`;
+    const payload = `AN-${plan}-${scope}-${interval}-${expiry}`;
+    const expectedSig = crypto_1.default
+        .createHmac("sha256", secret)
+        .update(payload)
+        .digest("hex")
+        .slice(0, 10);
+    if (sig !== expectedSig) {
+        throw new Error("Invalid license signature");
+    }
+    // Expiry check (month-based)
+    const now = new Date();
+    const exp = new Date(`${expiry}-01T00:00:00Z`);
+    exp.setMonth(exp.getMonth() + 1);
+    if (now >= exp) {
+        throw new Error("License expired");
+    }
+    return { plan, scope, interval, expiry };
 }

package/dist/paid/fixHints.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateFixHints = generateFixHints;
+function generateFixHints(findings) {
+    return findings
+        .filter((f) => f.impact === "HIGH" || f.impact === "CRITICAL")
+        .map((f) => ({
+        findingId: f.id,
+        explanation: "This issue may be exploitable. Review affected code paths and apply best-practice mitigations."
+    }));
+}

package/dist/paid/recommendations.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateRecommendations = generateRecommendations;
+function generateRecommendations(findings) {
+    return findings.map((f) => {
+        let text = "Review this finding carefully.";
+        if (f.check.includes("reentrancy")) {
+            text =
+                "Ensure all state changes occur before external calls. Consider using checks-effects-interactions or a reentrancy guard.";
+        }
+        else if (f.check.includes("delegatecall")) {
+            text =
+                "Avoid delegatecall where possible. If required, strictly validate target addresses and storage layout.";
+        }
+        else if (f.check.includes("low-level-call")) {
+            text =
+                "Validate return values of low-level calls and ensure failure handling is explicit.";
+        }
+        return {
+            findingId: f.id,
+            text
+        };
+    });
+}

package/dist/paid/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/profiles/profiles.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROFILES = void 0;
+exports.applyProfile = applyProfile;
+const IMPACT_ORDER = [
+    "LOW",
+    "MEDIUM",
+    "HIGH",
+    "CRITICAL"
+];
+function impactAtLeast(impact, min) {
+    if (!min)
+        return true;
+    return (IMPACT_ORDER.indexOf(impact) >= IMPACT_ORDER.indexOf(min));
+}
+exports.PROFILES = {
+    default: {
+        ignoreChecks: [
+            "naming-convention",
+            "solc-version",
+            "pragma",
+            "unused-return"
+        ],
+        minImpact: "LOW"
+    },
+    defi: {
+        ignoreChecks: [
+            "naming-convention",
+            "pragma",
+            "unused-return",
+            "low-level-calls",
+            "solc-version"
+        ],
+        minImpact: "MEDIUM"
+    },
+    protocol: {
+        ignoreChecks: [
+            "naming-convention",
+            "pragma",
+            "unused-return"
+        ],
+        minImpact: "HIGH"
+    },
+    strict: {
+        minImpact: "LOW"
+    }
+};
+function applyProfile(findings, profile) {
+    const rules = exports.PROFILES[profile];
+    return findings.filter((f) => {
+        if (rules.ignoreChecks &&
+            rules.ignoreChecks.includes(f.check)) {
+            return false;
+        }
+        return impactAtLeast(f.impact, rules.minImpact);
+    });
+}

package/dist/report/contest.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateContestReport = generateContestReport;
+function generateContestReport(findings) {
+    return findings.map((f, i) => `
+## Issue ${i + 1}: ${f.check}
+
+**Severity:** ${f.riskLevel}
+
+### Description
+${f.description}
+
+### Impact
+${f.impact}
+
+### Proof of Concept
+Manual review required.
+
+### Recommendation
+${f.recommendation ?? "No remediation suggestion provided."}
+`).join("\n\n---\n\n");
+}

package/dist/report/diff.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateDiffReport = generateDiffReport;
+function generateDiffReport(diff) {
+    let md = `# 🔍 Security Diff Report\n\n`;
+    md += `## 🆕 New Findings (${diff.added.length})\n\n`;
+    for (const f of diff.added) {
+        md += `- **${f.impact}** ${f.check}\n`;
+    }
+    md += `\n## 🔺 Risk Increased (${diff.increasedRisk.length})\n\n`;
+    for (const f of diff.increasedRisk) {
+        md += `- **${f.impact}** ${f.check}\n`;
+    }
+    if (diff.added.length === 0 &&
+        diff.increasedRisk.length === 0) {
+        md += `\n✅ **No new security risks introduced**\n`;
+    }
+    return md;
+}

package/dist/report/executive.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateExecutiveSummary = generateExecutiveSummary;
+function generateExecutiveSummary(findings) {
+    const counts = {
+        CRITICAL: 0,
+        HIGH: 0,
+        MEDIUM: 0,
+        LOW: 0,
+    };
+    for (const f of findings) {
+        counts[f.riskLevel]++;
+    }
+    const highRiskThemes = new Set();
+    for (const f of findings) {
+        if (f.riskScore >= 7) {
+            highRiskThemes.add(f.check);
+        }
+    }
+    let summary = `### Executive Summary\n\n`;
+    summary += `The automated analysis identified **${findings.length} actionable findings**. `;
+    summary += `The most significant risks are concentrated in **${counts.CRITICAL + counts.HIGH} high-impact issues**, `;
+    summary += `which should be reviewed immediately.\n\n`;
+    if (highRiskThemes.size > 0) {
+        summary += `**Primary risk themes identified:**\n`;
+        for (const theme of highRiskThemes) {
+            summary += `- ${theme}\n`;
+        }
+        summary += `\n`;
+    }
+    summary += `Lower-severity findings are primarily related to best-practice deviations and configuration hygiene.\n`;
+    return summary;
+}

package/dist/report/markdown.js

@@ -2,65 +2,52 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.generateMarkdown = generateMarkdown;
 function generateMarkdown(input) {
+    var _a;
+    let md = `# Smart Contract Audit Notes\n\n`;
+    if (input.diff) {
+        const { added, increasedRisk, unchanged } = input.diff;
+        md += `## 🔍 Pull Request Risk Summary\n\n`;
+        if (added.length === 0) {
+            md += `✅ **No new risks introduced**\n\n`;
+        }
+        else {
+            md += `### ❗ New Findings\n\n`;
+            for (const f of added) {
+                md += `- **${f.check}** — ${f.impact}\n`;
+            }
+            md += `\n`;
+        }
+        if (increasedRisk.length > 0) {
+            md += `### 🔺 Risk Increased\n\n`;
+            for (const f of increasedRisk) {
+                md += `- **${f.check}** — ${f.impact}\n`;
+            }
+            md += `\n`;
+        }
+        if (unchanged.length > 0) {
+            md += `### ⚠️ Existing Issues\n\n`;
+            for (const f of unchanged) {
+                md += `- ${f.check}\n`;
+            }
+            md += `\n`;
+        }
+        md += `---\n\n`;
+    }
+    md += `## Full Findings\n\n`;
+    md += `Total findings: **${input.findings.length}**\n\n`;
     const byImpact = {};
     for (const f of input.findings) {
-        const key = f.impact ?? "Unknown";
-        byImpact[key] ?? (byImpact[key] = []);
-        byImpact[key].push(f);
+        byImpact[_a = f.impact] ?? (byImpact[_a] = []);
+        byImpact[f.impact].push(f);
     }
-    let md = `# Smart Contract Audit Notes\n\n`;
-    md += `## Overview\n`;
-    md += `This document contains **automated audit notes** generated using static analysis tools.\n`;
-    md += `It is intended to **assist auditors and developers** during manual review.\n\n`;
-    md += `> ⚠️ **Disclaimer**\n`;
-    md += `> This report does **not** constitute a full security audit.\n`;
-    md += `> Findings represent **potential risk indicators**, not confirmed vulnerabilities.\n\n`;
-    md += `---\n\n`;
-    md += `## Scope\n`;
-    md += `- Target: Solidity smart contracts in the repository\n`;
-    md += `- Tooling: Slither (static analysis)\n`;
-    md += `- Coverage:\n`;
-    md += `  - Reentrancy patterns\n`;
-    md += `  - Low-level calls\n`;
-    md += `  - Compiler configuration issues\n`;
-    md += `  - Best-practice violations\n`;
-    md += `- Exclusions:\n`;
-    md += `  - Business logic correctness\n`;
-    md += `  - Economic & governance attacks\n`;
-    md += `  - Cross-protocol integrations\n\n`;
-    md += `---\n\n`;
-    md += `## Severity Interpretation\n`;
-    md += `- **High**: Likely exploitable patterns or critical misconfigurations\n`;
-    md += `- **Medium**: Context-dependent risks requiring review\n`;
-    md += `- **Low**: Best-practice or hygiene issues\n`;
-    md += `- **Informational**: Awareness items\n\n`;
-    md += `---\n\n`;
-    md += `## Summary\n`;
-    md += `Total findings identified: **${input.findings.length}**\n\n`;
     for (const impact of Object.keys(byImpact)) {
-        md += `## ${impact} Severity Findings\n\n`;
+        md += `## ${impact} Severity\n\n`;
         for (const f of byImpact[impact]) {
             md += `### ${f.check}\n\n`;
-            md += `${f.description.trim()}\n\n`;
-            if (f.locations.length > 0) {
-                md += `**Relevant Locations:**\n`;
-                for (const l of f.locations) {
-                    md += `- \`${l.contract ?? "?"}::${l.function ?? "?"}\``;
-                    if (l.lines)
-                        md += ` (lines ${l.lines.join(", ")})`;
-                    md += `\n`;
-                }
-                md += `\n`;
-            }
+            md += `${f.description}\n\n`;
             md += `---\n\n`;
         }
     }
-    md += `## Auditor Review Checklist\n`;
-    md += `- Validate exploitability of reentrancy paths\n`;
-    md += `- Review trust assumptions around low-level calls\n`;
-    md += `- Confirm compiler version risks are acceptable\n`;
-    md += `- Ensure findings align with protocol design intent\n\n`;
-    md += `---\n\n`;
-    md += `*Generated automatically. Manual review is strongly recommended.*\n`;
+    md += `*Generated automatically. Manual review required.*\n`;
     return md;
 }

package/dist/report/sarif.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateSarif = generateSarif;
+function generateSarif(findings) {
+    return {
+        version: "2.1.0",
+        $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "audit-notes",
+                        version: "0.1.0",
+                        rules: findings.map((f) => ({
+                            id: f.id,
+                            name: f.check,
+                            shortDescription: { text: f.check },
+                            fullDescription: { text: f.description },
+                            defaultConfiguration: {
+                                level: mapImpactToSarifLevel(f.impact)
+                            }
+                        }))
+                    }
+                },
+                results: findings.flatMap((f) => f.locations.map((loc) => ({
+                    ruleId: f.id,
+                    level: mapImpactToSarifLevel(f.impact),
+                    message: { text: f.description },
+                    locations: loc.file
+                        ? [
+                            {
+                                physicalLocation: {
+                                    artifactLocation: {
+                                        uri: loc.file
+                                    },
+                                    region: loc.lines
+                                        ? {
+                                            startLine: loc.lines[0],
+                                            endLine: loc.lines[loc.lines.length - 1]
+                                        }
+                                        : undefined
+                                }
+                            }
+                        ]
+                        : []
+                })))
+            }
+        ]
+    };
+}
+function mapImpactToSarifLevel(impact) {
+    switch (impact) {
+        case "CRITICAL":
+        case "HIGH":
+            return "error";
+        case "MEDIUM":
+            return "warning";
+        case "LOW":
+        default:
+            return "note";
+    }
+}

package/dist/risk/factors.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveRisk = deriveRisk;
+function deriveRisk(f) {
+    let score = 0;
+    const factors = [];
+    const text = `${f.check} ${f.description}`.toLowerCase();
+    if (text.includes("reentrancy")) {
+        score += 3;
+        factors.push("reentrancy");
+    }
+    if (text.includes("delegatecall")) {
+        score += 3;
+        factors.push("delegatecall");
+    }
+    if (text.includes("low level call")) {
+        score += 2;
+        factors.push("low-level-call");
+    }
+    if (text.includes("state")) {
+        score += 1;
+        factors.push("state-mutation");
+    }
+    let level = "LOW";
+    if (score >= 6)
+        level = "CRITICAL";
+    else if (score >= 4)
+        level = "HIGH";
+    else if (score >= 2)
+        level = "MEDIUM";
+    return { score, level, factors };
+}

package/dist/risk/score.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scoreRisk = scoreRisk;
+function scoreRisk(finding, factors) {
+    let score = 0;
+    if (factors.externalCall)
+        score += 3;
+    if (factors.usesDelegatecall)
+        score += 4;
+    if (factors.userControlledInput)
+        score += 3;
+    if (factors.mutatesState)
+        score += 2;
+    let impact = "LOW";
+    if (score >= 8)
+        impact = "CRITICAL";
+    else if (score >= 6)
+        impact = "HIGH";
+    else if (score >= 4)
+        impact = "MEDIUM";
+    return {
+        ...finding,
+        riskScore: score,
+        impact
+    };
+}

package/dist/risk/scorer.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeRiskScore = computeRiskScore;
+exports.riskBand = riskBand;
+const WEIGHTS = {
+    usesAssembly: 1,
+    usesDelegatecall: 3,
+    externalCall: 2,
+    mutatesState: 2,
+    highComplexity: 2,
+    touchesCoreContract: 3,
+    userControlledInput: 3
+};
+function computeRiskScore(factors) {
+    let score = 0;
+    for (const [k, v] of Object.entries(factors)) {
+        if (v)
+            score += WEIGHTS[k];
+    }
+    return Math.min(score, 10);
+}
+function riskBand(score) {
+    if (score >= 8)
+        return "CRITICAL";
+    if (score >= 6)
+        return "HIGH";
+    if (score >= 4)
+        return "MEDIUM";
+    return "LOW";
+}

package/dist/risk/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// src/risk/types.ts
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/types/finding.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

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