feat(compiler): multi-compiler Solidity compatibility and diagnostic matrix (#76)

[covenantalade]

Summary

Closes #76

Implements a comprehensive, production-grade **Multi-Compiler Solidity Compatibility and Diagnostic Matrix** for  

ChainProof.

Smart contracts frequently specify wide or floating pragma version ranges (e.g., `pragma solidity ^0.8.0;` or     

pragma solidity >=0.7.0 <0.9.0;), which introduces severe audit and deployment blindspots when assumptions about
compiler behavior diverge across minor and patch releases. This PR introduces a deterministic TypeScript toolchain
for multi-compiler version evaluation, cross-file pragma constraint solving, artifact normalization, sandboxed
compilation, and differential comparison.

---                                                                                                               
                                                                                                                  
### Key Architectural Components                                                                                  
                                                                                                                  
#### 1. Zero-Dependency SemVer & Pragma Constraint Solver                                                         
- **Pure SemVer Parser & Solver (`packages/core/src/compiler/semver.ts`):** Full SemVer specification support for 

carets (^), tildes (~), wildcards (*, x), hyphen ranges, inequalities (>=, <=, >, <), conjunctions,
and disjunctions (||).
- Pragma Constraint Engine (packages/core/src/compiler/pragma.ts): Extracts AST/regex pragmas, evaluates
floating/overly broad/security-sensitive ranges, and resolves multi-file dependency trees to detect unsatisfiable or
conflicting import pragmas with pairwise conflict reporting.

#### 2. Compiler Registry & Codegen Hazards Database                                                              
- **Solidity Release Matrix (`packages/core/src/compiler/matrix.ts`):** Complete registry of releases from `0.4.  

11to0.8.28 mapping features, capabilities (checked arithmetic, custom errors, UDVTs, transient storage, push0, viaIR, ABI coder v2, storage layout output), and default EVM targets. - **Codegen Bugs & Hazards (SOL_CODEGEN_BUGS):** Curated database of known Solidity compiler code generation bugs (SOL-BUG-2024-1transient storage corruption,SOL-BUG-2023-1PUSH0 EVM mismatch,SOL-BUG-2022-7signed immutables sign-extension,SOL-BUG-2021-3` storage byte packing, etc.) mapped to AST triggering conditions.
- Breaking Changes Registry: Detailed syntax and semantic migration registry across minor compiler families
(0.4 $\to$ 0.5 $\to$ 0.6 $\to$ 0.7 $\to$ 0.8).

#### 3. Compiler Adapter Layer & Sandboxed Execution                                                              
- **Pluggable Adapter (`packages/core/src/compiler/adapter.ts`):**                                                
  - `SimulatedCompilerAdapter`: 100% offline, deterministic embedded simulator that generates normalized AST-based

ABIs, calculates exact storage packing layouts, and models version-specific syntax/hazards.
- NativeSolcAdapter: Sandboxed process runner for local verified compiler binaries with memory and execution
timeout limits.
- Cryptographic Binary Verification (packages/core/src/compiler/checksums.ts): SHA-256 binary validation
database (OFFICIAL_SOLC_CHECKSUMS) with zero dynamic network download requirements in CI.
- Process Isolation & Sanitization (packages/core/src/compiler/sandbox.ts): Environment scrubbing (redacts
API keys and secrets), compiler cache corruption validation, and error sanitization (strips absolute host paths).

#### 4. Artifact Normalization & Differential Comparison Engine                                                   
- **Normalized Artifacts (`packages/core/src/compiler/normalizer.ts`):** Pure Keccak-256 implementation for 4-byte

function selectors and 32-byte event topics, storage layout packing and slot hash computation, and bytecode opcode
parsing (PUSH0, TSTORE, TLOAD).
- Cross-Compiler Differential Comparator (packages/core/src/compiler/comparator.ts): Compares compilation
outputs across versions:
- Storage Layout Drift: Detects slot collisions and offset shifts (critical for upgradeable proxy storage
corruption).
- ABI Diffs: Added, removed, or mutated function selectors, events, and errors.
- Bytecode & EVM Diffs: Size delta (bytes/percent), PUSH0 introduction hazards, and transient storage usage.
- Diagnostic & Finding Diffs: Compiler warnings and security detector findings.

#### 5. Static Compatibility Rules (`CP-SOL-001` through `CP-SOL-010`)                                            
- **`CP-SOL-001`**: Floating Pragma Directive (`Low`)                                                             
- **`CP-SOL-002`**: Unsatisfiable / Conflicting Import Pragmas (`High`)                                           
- **`CP-SOL-003`**: Overly Broad Version Range (`Medium`)                                                         
- **`CP-SOL-004`**: Outdated / End-of-Life Compiler (<0.8.0) (`High`)                                             
- **`CP-SOL-005`**: Known Compiler Code-Generation Bug / Hazard (`Critical` / `High`)                             
- **`CP-SOL-006`**: PUSH0 Opcode EVM Incompatibility Risk (`Low` / `High`)                                        
- **`CP-SOL-007`**: Storage Layout Collision / Slot Drift (`Critical`)                                            
- **`CP-SOL-008`**: ABI / Interface Breaking Drift (`High`)                                                       
- **`CP-SOL-009`**: Transient Storage Lifecycle Hazard (`Medium`)                                                 
- **`CP-SOL-010`**: Unverified Compiler Binary / Checksum Mismatch (`Critical`)                                   
- Integrated into the core `scan()` workflow via `detectCompilerCompatibility()`.                                 
                                                                                                                  
#### 6. CLI Commands & REST API Endpoints                                                                         
- **CLI Commands (`packages/cli/src/commands/compiler.ts`):**                                                     
  - `chainproof compiler inspect <targets...>`                                                                    
  - `chainproof compiler matrix <targets...>`                                                                     
  - `chainproof compiler compare <targets...>`                                                                    
  - `chainproof compiler audit <targets...>`                                                                      
  - Flags: `--format <json|markdown|table>`, `--output <file>`, `--config <file>`, `--versions <list>`, `--fail-on

, --fail-on-drift. - **REST Endpoints (packages/server/src/routes/compiler.ts&openapi.yaml):** - POST /compiler/inspect-POST /compiler/matrix -POST /compiler/compare-POST /compiler/audit`

#### 7. Documentation & Fixtures
- Comprehensive reference documentation in [`docs/compiler-matrix.md`](docs/compiler-matrix.md).
- Solidity test fixtures in [`examples/contracts/compiler/`](examples/contracts/compiler/) covering secure pinned

contracts, floating/broad pragmas, incompatible imports, storage layout collisions, and transient storage.

--- 
    
### Verification & Test Coverage

- **Production Code:** 5,531 LOC TypeScript across `@chainproof/core`, `@chainproof/cli`, and `@chainproof/server`.
- **Test Suites:** 1,198 LOC tests across 10 dedicated test suites covering SemVer, pragma solving, compiler      

matrix, adapters, differential comparator, static rules, configuration migration, adversarial bounds, public APIs,
CLI commands, and server routes.
- Repository Validation:
- npm run build: All 6 workspace packages build cleanly with 0 errors (core, server, cli, hardhat- plugin, vscode-extension, github-action).
- npm run lint: 0 ESLint errors.
- npm test: 52/52 test suites passed, 437/437 unit & integration tests passing.

[Nanle-code]

@covenantalade Great job