feat: Structured diff engine to detect vulnerability regressions between commits

[Nanle-code]

Overview

ChainProof produces a standalone scan result per invocation with no way to compare results across commits or branches. Teams cannot easily answer: Did this PR introduce new vulnerabilities? or Did we fix the issues from last sprint? A diff engine addresses this gap.

Problem

Without diff-aware scanning:

• A PR touching 2 files out of 100 still surfaces findings from all 100 files
• No distinction between pre-existing and newly introduced issues
• Re-auditing the full project on every PR is expensive and noisy

Proposed Design

interface ScanDiff {
  introduced: Finding[];
  resolved: Finding[];
  persisted: Finding[];
  summary: {
    newCritical: number;
    newHigh: number;
    resolvedTotal: number;
  }
}

Findings are matched across scans by fingerprint: SHA-256(ruleId + normalized_path + line + snippet_hash) with ±3 line tolerance for minor code movements.

Usage Modes

CLI — compare two JSON reports:

chainproof diff old-results.json new-results.json

CLI — compare against git ref:

chainproof scan contracts/ --diff HEAD~1

GitHub Action — auto-diff against base branch on PRs, only fail CI on introduced findings above min-severity.

Diff Report Format

## ChainProof Diff Report

### Newly Introduced (2)
| Rule   | File                | Line | Severity |
|--------|---------------------|------|----------|
| CP-107 | contracts/Vault.sol | 42   | Critical |

### Resolved Since Last Scan (1)
| Rule   | File               | Line | Severity |
|--------|--------------------|------|----------|
| CP-115 | contracts/Auth.sol | 18   | High     |

Acceptance Criteria

• diffScans(oldResult, newResult): ScanDiff exported from core
• chainproof diff <old.json> <new.json> CLI command
• chainproof scan --diff flag using git stash/checkout
• GitHub Action diff mode comparing against base branch
• PR comment updated to show diff-aware summary
• Diff report in Markdown and JSON formats

[444notdotun]

hi, i would love to work on this project