Pull Request: Unified AST, Extensible Rule Engine & Auto-Fix Suite (#186, #187, #189, #190)

[elizabetheonoja-art]

📝 Description
This PR executes a foundational refactor of the GasGuard ecosystem. It bridges the gap between different smart contract languages by introducing a Common AST (CAST) and unlocks community-driven growth through a new Plugin System. Furthermore, it completes the developer loop with Auto-Fix capabilities and a plug-and-play GitHub Action.

🎯 Key Changes by Module

1. Unified AST Representation (Create a unified AST representation across Solidity, Rust, and Vyper. #186)
   The CAST Schema: Defined a language-agnostic Abstract Syntax Tree in libs/ast/ that maps high-level constructs (Loops, Variable Assignments, Storage Access) across Solidity, Rust (Soroban), and Vyper.

Adapters: Implemented specialized parsers in libs/parsers/ that normalize language-specific outputs into the GasGuard CAST format.

2. Plugin System & Rule Extensibility (Enable external contributors to add custom analysis rules. #187)
   Plugin Core: Decoupled the rule engine. Rules are now standalone TypeScript modules that implement a standardized GasRule interface.

Dynamic Loading: The CLI now supports --plugin , allowing external contributors to run custom analysis without modifying the core codebase.

3. GitHub Action for CI/CD (Create a GitHub Action for automated contract scanning. #189)
   Automation: Created a Docker-based GitHub Action that scans contracts on every PR.

PR Annotations: Findings are now injected directly into the GitHub "Files Changed" view as line-item comments, including gas-saving estimates.

4. Auto-Fix Engine (Automatically apply safe gas optimization fixes #190)
   Safe Transformations: Introduced the libs/auto-fix/ engine which can automatically apply "Safe" optimizations (e.g., changing memory to calldata in Solidity or optimizing vec iterations in Rust).

CLI Preview: Added gasguard fix --preview to show a git-style diff before applying changes.

💻 Implementation Detail: The Plugin Interface
TypeScript
// packages/types/ast/plugin.ts
export interface GasRule {
id: string;
meta: {
description: string;
impact: 'High' | 'Medium' | 'Low';
};
// Works on the Unified AST regardless of source language
check(node: CASTNode): Diagnostic | null;
fix?(node: CASTNode): Patch | null;
}
✅ Acceptance Criteria Checklist
[x] Cross-Language: A single rule can now detect "Unused State Variables" in both Solidity and Rust files.

[x] Extensibility: Successfully loaded a sample "Third-Party" rule from an external directory.

[x] Automation: Verified that the GitHub Action fails the build if a "High" impact gas leak is detected.

[x] Actionable: gasguard fix successfully generates valid .patch files for detected issues.

🚀 How to Verify
Test Unified AST: Run npm run test:ast to see Solidity and Rust snippets generate the same CAST structure.

Test Auto-Fix: ```bash
cd apps/cli && ts-node src/index.ts fix ./contracts/Vulnerable.sol --auto-fix

CI Simulation: Run the GitHub Action locally using act or push to a test repository to see the PR annotations in action.

🔗 Linked Issues
Closes #186,
Closes #187,
Closes #189,
Closes #190

[drips-wave]

@elizabetheonoja-art Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits