docs: add comprehensive submodule usage guide
Details how to use this repository as a Git submodule in other projects. Includes: - Setup instructions - Script usage examples - CI/CD integration - Customization guide - Troubleshooting 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Administrator
398
SUBMODULE_USAGE.md
Normal file
398
SUBMODULE_USAGE.md
Normal file
@@ -0,0 +1,398 @@
|
||||
# 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 ✅
|
||||
Reference in New Issue
Block a user