feat: Add comprehensive utils package, importer tests, and fix tag semantics

[AdekunleBamz]

Summary

This PR adds a comprehensive utility package with formatting and validation functions, extensive test coverage for the importer service, and fixes a bug in tag application semantics.

Changes

🛠️ New Utility Functions (runner/utils/format.go)

Formatting Utilities:

• FormatDuration() - Human-readable duration formatting (e.g., "1h 23m 45s", "500ms")
• FormatBytes() - Byte count formatting with appropriate units (GB, MB, KB, B)
• FormatGas() - Gas value formatting (Ggas, Mgas, Kgas)
• FormatPercentage() - Ratio to percentage conversion with configurable precision
• FormatTimestamp() / ParseTimestamp() - Timestamp formatting and parsing

Parsing Utilities:

• ParseDuration() - Parse human-readable duration strings
• ParseGasLimit() - Parse gas limits with suffixes (50G, 50e9, 50Ggas, 100M)

String Utilities:

• TruncateString() - Truncate strings with ellipsis
• TruncateMiddle() - Truncate in the middle (useful for hashes/addresses)

Validation Utilities:

• IsValidHexAddress() - Validate Ethereum addresses (0x + 40 hex chars)
• IsValidHexHash() - Validate 32-byte hex hashes (0x + 64 hex chars)

Statistics:

• CalculateStats() - Calculate mean, standard deviation, min, max, and median

Safety Utilities:

• SafeDivide() / SafeDivideUint64() - Zero-safe division helpers

✅ Test Coverage

runner/utils/utils_test.go - 50+ unit tests covering:

• All formatting functions with various inputs
• Parsing functions with valid and invalid inputs
• Validation functions with edge cases
• Statistical calculations

runner/importer/service_test.go - Tests for:

• MergeMetadata tag application semantics
• BenchmarkRun ID reuse behavior
• CreatedAt field filling
• Complete flag setting

🐛 Bug Fix

Fixed tag application order in MergeMetadata():

• Before: srcTag was incorrectly applied to imported runs, destTag to existing runs
• After: destTag (dest-tag flag) correctly applies to imported runs, srcTag (src-tag flag) fills missing tags on existing runs

This aligns the implementation with the CLI flag documentation:

• --src-tag: "Tag to apply to existing metadata runs"
• --dest-tag: "Tag to apply to imported metadata runs"

Testing

# Run all tests
go test ./runner/utils/... ./runner/importer/...

# Run with verbose output
go test -v ./runner/utils/... ./runner/importer/...

[cb-heimdall]

🟡 Heimdall Review Status

Requirement	Status	More Info
Reviews	🟡 0/1	Denominator calculation Show calculation 1 if user is bot 0 1 if user is external 0 2 if repo is sensitive 0 From .codeflow.yml 1 Additional review requirements Show calculation Max 0 0 From CODEOWNERS 0 Global minimum 0 Max 1 1 1 if commit is unverified 1 Sum 2

[meyer9]

This is all unused, please remove

[cb-heimdall]

Review Error for meyer9 @ 2026-01-06 22:50:18 UTC
User failed mfa authentication, see go/mfa-help