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