# 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:

```bash
# 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:

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
# 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

```bash
# 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:

```bash
# 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:

```bash
# 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:

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

# Customize for your project
vim docs/README.md
```

## CI/CD Integration

### GitHub Actions Example

```yaml
# .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

```yaml
# .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**
   ```bash
   # Pre-commit hook
   ./tools/ai-toolset/scripts/test.sh unit
   ./tools/ai-toolset/scripts/check-compliance.sh
   ```

3. **Run Before Push**
   ```bash
   # 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

```bash
git submodule update --init --recursive
```

### Permission Denied on Scripts

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

### Container Not Found

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

### Custom Script Directory

```bash
# 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 ✅