feat(forge): enhance gas snapshot diff with configurable sorting and improved output

[silvekkk]

Improves the output of forge snapshot --diff with configurable sorting and better visibility into test changes.

Currently the diff output always sorts by percentage change in ascending order, which makes it hard to quickly find tests with large absolute gas changes. Also, new tests that don't exist in the baseline snapshot are silently ignored, which can be confusing.

adds a --diff-sort flag to control sort order and improves the output formatting.

New flag --diff-sort with 4 options:

• percentage - sort by percentage change ascending (default, preserves current behavior)
• percentage-desc - sort by percentage change descending
• absolute - sort by absolute gas change ascending
• absolute-desc - sort by absolute gas change descending

Output improvements:

• Visual indicators for change direction
• Show before and after gas values
• Display new tests that aren't in the snapshot
• Add summary line with statistics
• Include contract name prefix to disambiguate tests with same name

Before

testSmallChange7() (gas: +3 (+0.006%)) 
testSmallChange3() (gas: +5 (+0.010%)) 
testSmallChange6() (gas: -8 (-0.016%)) 
testSmallChange1() (gas: +10 (+0.020%)) 
testSmallChange4() (gas: +15 (+0.030%)) 
testSmallChange2() (gas: -20 (-0.040%)) 
testMediumChange() (gas: -500 (-2.000%)) 
testBigProblem() (gas: +8000 (+16.000%)) 
testCritical() (gas: +12000 (+24.000%)) 
Overall gas change: +19505 (+3.901%)

After (default behavior, fully compatible)

↑ Token::testSmallChange7() (gas: 50000 → 50003 | +3 +0.006%)
↑ Token::testSmallChange3() (gas: 50000 → 50005 | +5 +0.010%)
↓ Token::testSmallChange6() (gas: 50000 → 49992 | -8 -0.016%)
↑ Token::testSmallChange1() (gas: 50000 → 50010 | +10 +0.020%)
↑ Token::testSmallChange4() (gas: 50000 → 50015 | +15 +0.030%)
↓ Token::testSmallChange2() (gas: 50000 → 49980 | -20 -0.040%)
↓ Token::testMediumChange() (gas: 25000 → 24500 | -500 -2.000%)
↑ Counter::testBigProblem() (gas: 50000 → 58000 | +8000 +16.000%)
↑ Counter::testCritical() (gas: 50000 → 62000 | +12000 +24.000%)

New tests:
  + Counter::testNewFeature()

--------------------------------------------------------------------------------
Total tests: 9, ↑ 6, ↓ 3, ━ 0
Overall gas change: +19505 (+3.901%)

After (--diff-sort percentage-desc)

↑ Counter::testCritical() (gas: 50000 → 62000 | +12000 +24.000%)
↑ Counter::testBigProblem() (gas: 50000 → 58000 | +8000 +16.000%)
↓ Token::testMediumChange() (gas: 25000 → 24500 | -500 -2.000%)
↓ Token::testSmallChange2() (gas: 50000 → 49980 | -20 -0.040%)
↑ Token::testSmallChange4() (gas: 50000 → 50015 | +15 +0.030%)
↑ Token::testSmallChange1() (gas: 50000 → 50010 | +10 +0.020%)
↓ Token::testSmallChange6() (gas: 50000 → 49992 | -8 -0.016%)
↑ Token::testSmallChange3() (gas: 50000 → 50005 | +5 +0.010%)
↑ Token::testSmallChange7() (gas: 50000 → 50003 | +3 +0.006%)

New tests:
  + Counter::testNewFeature()

--------------------------------------------------------------------------------
Total tests: 9, ↑ 6, ↓ 3, ━ 0
Overall gas change: +19505 (+3.901%)

Usage

# Default behavior unchanged
forge snapshot --diff

# Sort by largest percentage changes first
forge snapshot --diff --diff-sort percentage-desc

# Sort by largest absolute gas changes first
forge snapshot --diff --diff-sort absolute-desc

This is fully backward compatible. Default behavior remains identical to the current implementation.

[onbjerg]

makes sense to me

[onbjerg]

please check the ci failures though

[grandizzy]

mind that this will be a breaking change as the files are committed in git and will yield diffs when we change, probably not an issue though but people will need to refresh their repos cc @zerosnacks

[silvekkk]

mind that this will be a breaking change as the files are committed in git and will yield diffs when we change, probably not an issue though but people will need to refresh their repos cc @zerosnacks

@grandizzy Hi, this doesn't change the snapshot file format itself - only the terminal output when running forge snapshot --diff.

The .gas-snapshot file format remains unchanged:

Counter:testDeposit() (gas: 50000)

The changes only affect the diff display output (terminal only):

↑ Counter::testDeposit() (gas: 50000 → 52000 | +2000 +4.000%)

Let me know if you want me to change the .gas-snapshot file format

[grandizzy]

Ah, thanks for clarification, got the wrong impression that it is changing