mev-beta/SUBMODULE_USAGE.md

Using This Repository as a Git Submodule

This repository can be included in other projects as a Git submodule to provide comprehensive audit and testing infrastructure.

Repository Information

Submodule URL: ssh://git@194.163.145.241:2222/administrator/ai-toolset

What This Provides

🔧 Audit & Testing Scripts (4 comprehensive scripts)

1. scripts/audit.sh - 12-section codebase audit

   • SPEC.md compliance
   • Go code quality
   • Security scanning
   • Concurrency safety
   • Error handling
   • Documentation coverage
   • Test coverage
   • Dependencies
   • Contract bindings
   • Build verification
   • File organization
   • Git status

2. scripts/test.sh - 7 test types

   • Unit tests
   • Integration tests
   • Race detection
   • Benchmarks
   • Coverage reports
   • Contract tests
   • Package-specific tests

3. scripts/check-compliance.sh - SPEC.md validation

   • 8 MUST DO requirements
   • 7 MUST NOT DO violations
   • Architecture requirements
   • Foundry integration
   • Development scripts

4. scripts/check-docs.sh - Documentation coverage

   • Package documentation
   • Exported function comments
   • Exported type comments
   • README files
   • Inline comment density
   • API documentation
   • Example code

📚 Comprehensive Documentation (1,700+ lines)

• SPEC.md - Technical specification and requirements
• docs/AUDIT_AND_TESTING.md - Complete testing guide (600+ lines)
• docs/SCRIPTS_REFERENCE.md - All scripts documented (700+ lines)
• docs/README.md - Documentation index and navigation
• docs/DEVELOPMENT_SETUP.md - Environment setup guide
• docs/REFACTORING_PLAN.md - Systematic refactoring plan

🛠️ Development Infrastructure

• scripts/dev.sh - Unified development script
• Container-based development (Podman/Docker)
• Foundry integration for contracts
• Go binding generation
• Complete development workflow

Adding as a Submodule

Option 1: Add to Parent Repository

From your parent repository:

# Add as submodule
git submodule add ssh://git@194.163.145.241:2222/administrator/ai-toolset tools/ai-toolset

# Initialize and update
git submodule update --init --recursive

# Commit the submodule
git add .gitmodules tools/ai-toolset
git commit -m "Add ai-toolset submodule for audit/testing infrastructure"

Option 2: Clone Repository with Submodules

If cloning a repository that already includes this submodule:

# Clone with submodules
git clone --recursive <parent-repo-url>

# Or if already cloned
git submodule update --init --recursive

Using the Scripts

Once added as a submodule, you can use the scripts from your parent repository:

Direct Usage

# Run audit
./tools/ai-toolset/scripts/audit.sh

# Run tests
./tools/ai-toolset/scripts/test.sh all

# Check compliance
./tools/ai-toolset/scripts/check-compliance.sh

# Check documentation
./tools/ai-toolset/scripts/check-docs.sh

Symlink Setup (Recommended)

Create symlinks in your parent repository for easier access:

# Create scripts directory in parent repo
mkdir -p scripts

# Symlink audit scripts
ln -s ../tools/ai-toolset/scripts/audit.sh scripts/audit.sh
ln -s ../tools/ai-toolset/scripts/test.sh scripts/test.sh
ln -s ../tools/ai-toolset/scripts/check-compliance.sh scripts/check-compliance.sh
ln -s ../tools/ai-toolset/scripts/check-docs.sh scripts/check-docs.sh

# Now use from parent repo
./scripts/audit.sh
./scripts/test.sh all

Copy and Customize

If you need to customize the scripts for your project:

# Copy scripts to your repository
cp -r tools/ai-toolset/scripts/* ./scripts/

# Customize as needed
vim scripts/audit.sh

# Commit your customized versions
git add scripts/
git commit -m "Add customized audit scripts"

Updating the Submodule

Update to Latest Version

# Navigate to submodule
cd tools/ai-toolset

# Pull latest changes
git pull origin v2-master-dev

# Go back to parent repo
cd ../..

# Commit the submodule update
git add tools/ai-toolset
git commit -m "Update ai-toolset to latest version"

Update All Submodules

# Update all submodules to latest
git submodule update --remote --merge

# Commit updates
git add .
git commit -m "Update all submodules"

Adapting to Your Project

1. SPEC.md Customization

The included SPEC.md is specific to the MEV bot project. For your project:

# Copy as template
cp tools/ai-toolset/SPEC.md ./SPEC.md

# Customize for your project
vim SPEC.md

# The check-compliance.sh script will use your SPEC.md

2. Script Configuration

Most scripts are project-agnostic, but you can configure them:

# Set environment variables
export GO_CONTAINER=your-go-container
export COVERAGE_THRESHOLD=80

# Run with custom settings
./tools/ai-toolset/scripts/test.sh coverage

3. Documentation Structure

Use the documentation structure as a template:

# Copy documentation structure
cp -r tools/ai-toolset/docs/* ./docs/

# Customize for your project
vim docs/README.md

CI/CD Integration

GitHub Actions Example

# .github/workflows/audit.yml
name: Code Audit

on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: recursive

      - name: Run Audit
        run: ./tools/ai-toolset/scripts/audit.sh

      - name: Check Compliance
        run: ./tools/ai-toolset/scripts/check-compliance.sh

      - name: Run Tests
        run: ./tools/ai-toolset/scripts/test.sh all

GitLab CI Example

# .gitlab-ci.yml
audit:
  stage: test
  script:
    - git submodule update --init --recursive
    - ./tools/ai-toolset/scripts/audit.sh
    - ./tools/ai-toolset/scripts/check-compliance.sh
    - ./tools/ai-toolset/scripts/test.sh all

Available Documentation

All documentation is available in the docs/ directory:

• Start Here: docs/README.md - Documentation index
• Setup: docs/DEVELOPMENT_SETUP.md - Environment setup
• Testing: docs/AUDIT_AND_TESTING.md - Complete testing guide
• Scripts: docs/SCRIPTS_REFERENCE.md - All scripts documented
• Planning: docs/REFACTORING_PLAN.md - Refactoring guide

Script Capabilities Summary

audit.sh

✓ 12 comprehensive checks ✓ Colored output with severity levels ✓ SPEC.md compliance validation ✓ Security scanning ✓ Code quality analysis

test.sh

✓ 7 test types ✓ Container-based execution ✓ Coverage reports (HTML + percentage) ✓ Verbose mode support ✓ Package-specific testing

check-compliance.sh

✓ MUST DO requirements (8 checks) ✓ MUST NOT DO violations (7 checks) ✓ Architecture validation ✓ Foundry integration check ✓ Development script verification

check-docs.sh

✓ Package documentation ✓ Exported symbols coverage ✓ README file validation ✓ Comment density analysis ✓ >80% coverage target

Exit Codes

All scripts use consistent exit codes:

• 0 - Success (all checks passed)
• 1 - Failure (violations found, tests failed)
• 127 - Command not found
• 255 - Container error

Best Practices

1. Keep Submodule Updated

   • Regularly pull latest changes
   • Review release notes before updating

2. Run Before Commits

   # Pre-commit hook
   ./tools/ai-toolset/scripts/test.sh unit
   ./tools/ai-toolset/scripts/check-compliance.sh
   

3. Run Before Push

   # Pre-push validation
   ./tools/ai-toolset/scripts/test.sh all
   ./tools/ai-toolset/scripts/audit.sh
   ./tools/ai-toolset/scripts/check-docs.sh
   

4. CI/CD Integration

   • Run audit on every push
   • Block merges on failures
   • Generate coverage reports

Troubleshooting

Submodule Not Initialized

git submodule update --init --recursive

Permission Denied on Scripts

chmod +x tools/ai-toolset/scripts/*.sh

Container Not Found

# Update container name in environment
export GO_CONTAINER=your-container-name
./tools/ai-toolset/scripts/test.sh unit

Custom Script Directory

# Scripts look for Go code in ./pkg/ by default
# For different structure, customize scripts or use symlinks

Support

For issues or questions:

1. Check documentation in docs/
2. Review docs/SCRIPTS_REFERENCE.md
3. Check docs/AUDIT_AND_TESTING.md for testing guidance
4. Review commit history for examples

Version Information

This infrastructure includes:

• Scripts: 4 audit/test scripts + 5 development scripts
• Documentation: 1,700+ lines across 5 comprehensive guides
• Code Quality: Fixed race conditions, added validation, eliminated silent failures
• Build Status: ✅ All packages compile
• Test Coverage: >70% target with detailed reports

---

Repository: ssh://git@194.163.145.241:2222/administrator/ai-toolset Branch: v2-master-dev Last Updated: 2025-11-11 Status: Production Ready ✅