Contributing to AIGovHub CLI

# Clone the repository
git clone https://github.com/aigovhub/aigovhub-cli
cd aigovhub-cli
 
# Create virtual environment and install dependencies
uv sync --all-extras
 
# Or with pip
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Verify Setup

# Run tests
uv run pytest
 
# Run linter
uv run ruff check src/
 
# Run type checker
uv run ty check src/
 
# Test CLI
uv run aigovhub --version

Install Pre-commit Hooks

uv run pre-commit install

Development Workflow

1. Create a Branch

git checkout -b feature/my-feature
# or
git checkout -b fix/bug-description

Branch naming conventions:

feature/ - New features
fix/ - Bug fixes
docs/ - Documentation
refactor/ - Code refactoring
test/ - Test improvements

2. Make Changes

Write your code following our guidelines (see below).

3. Run Tests

# Run all tests
uv run pytest
 
# Run specific test file
uv run pytest tests/unit/test_detection.py
 
# Run with coverage
uv run pytest --cov=aigovhub --cov-report=term-missing

4. Run Linting

# Check for issues
uv run ruff check src/ tests/
 
# Auto-fix issues
uv run ruff check src/ tests/ --fix
 
# Format code
uv run ruff format src/ tests/

5. Run Type Checking

uv run ty check src/

6. Commit Changes

Write clear commit messages:

git commit -m "feat: add support for ONNX model detection"
git commit -m "fix: handle empty requirements.txt gracefully"
git commit -m "docs: add CI/CD integration guide"

Follow Conventional Commits:

feat: - New feature
fix: - Bug fix
docs: - Documentation
test: - Tests
refactor: - Refactoring
chore: - Maintenance

7. Open a Pull Request

Push your branch and open a PR:

git push origin feature/my-feature

In your PR description:

Describe what the PR does
Reference related issues
Include test instructions

Code Guidelines

Style

We use Ruff for linting and formatting:

# Check style
uv run ruff check src/
 
# Format code
uv run ruff format src/

Type Hints

All code should have type hints:

# Good
def detect_libraries(dependencies: list[Dependency]) -> list[DetectionSignal]:
    ...
 
# Avoid
def detect_libraries(dependencies):
    ...

Documentation

Document public functions and classes:

def aggregate(self, signals: list[DetectionSignal]) -> list[AISystem]:
    """Aggregate detection signals into AI systems.
 
    Args:
        signals: List of detection signals from various detectors
 
    Returns:
        List of identified AI systems with aggregated confidence
    """

Testing

Write tests for new functionality:

# tests/unit/test_my_feature.py
import pytest
from aigovhub.my_module import my_function
 
class TestMyFunction:
    def test_basic_case(self):
        result = my_function("input")
        assert result == "expected"
 
    def test_edge_case(self):
        result = my_function("")
        assert result is None

Project Structure

src/aigovhub/
├── cli/              # CLI commands and output
├── core/             # Shared types and utilities
├── scanner/          # Repository scanning
├── detection/        # AI detection logic
│   └── signals/      # Signal detectors
├── llm/              # LLM provider abstraction
├── sbom/             # SBOM generation
└── artifact/         # Artifact management

Adding a New Feature

Adding a Signal Detector

Create the detector in detection/signals/:

# detection/signals/new_signal.py
from aigovhub.detection.signals.base import SignalDetector
 
class NewSignal(SignalDetector):
    @property
    def name(self) -> str:
        return "new_signal"
 
    @property
    def priority(self) -> int:
        return 3  # Lower = higher priority
 
    def detect(self, repository, dependencies):
        signals = []
        # Your detection logic
        return signals

from aigovhub.detection.signals.new_signal import NewSignal
 
self.detectors = [
    LibrarySignal(),
    ModelFileSignal(),
    NewSignal(),  # Add here
    APIUsageSignal(),
]

Add tests:

# tests/unit/test_new_signal.py
class TestNewSignal:
    def test_detects_expected_pattern(self, temp_repo):
        # ...

Adding an LLM Provider

Create the provider in llm/providers/:

# llm/providers/new_provider.py
from aigovhub.llm.providers.base import LLMProvider
 
class NewProvider(LLMProvider):
    @property
    def name(self) -> str:
        return "new_provider"
 
    def complete(self, prompt, **kwargs):
        # Implementation
        pass

PROVIDERS = {
    "anthropic": AnthropicProvider,
    "openai": OpenAIProvider,
    "new_provider": NewProvider,
}

Adding a CLI Command

Add command in cli/app.py:

@app.command()
def new_command(
    option: str = typer.Option(..., help="Description"),
) -> None:
    """Command description."""
    # Implementation

Add tests:

# tests/unit/test_cli.py
def test_new_command(runner):
    result = runner.invoke(app, ["new-command", "--option", "value"])
    assert result.exit_code == 0

Testing

Running Tests

# All tests
uv run pytest
 
# With coverage
uv run pytest --cov=aigovhub
 
# Specific tests
uv run pytest tests/unit/test_detection.py -v
 
# Only integration tests
uv run pytest tests/integration/ -v

Test Categories

Unit tests (tests/unit/): Test individual components
Integration tests (tests/integration/): Test workflows

Test Fixtures

Use pytest fixtures in conftest.py:

@pytest.fixture
def temp_ml_repo(tmp_path):
    """Create a temporary ML repository for testing."""
    # Setup
    return path

Pull Request Process

Ensure all tests pass
Ensure linting passes
Update documentation if needed
Request review from maintainers
Address review feedback
Squash and merge when approved

Release Process

Releases are managed by maintainers:

Update version in src/aigovhub/__init__.py
Update CHANGELOG.md
Create release tag
Publish to PyPI

Getting Help

Questions: GitHub Discussions
Bugs: GitHub Issues
Security: security@aigovhub.com (private disclosure)

Recognition

Contributors are recognized in:

CONTRIBUTORS.md
Release notes
README acknowledgments

Thank you for contributing to AIGovHub!