# Troubleshooting Guide

This guide helps you resolve common issues when using augint-library.

## 🔍 Quick Diagnosis

```mermaid
graph TD
    A[Issue?] --> B{Type?}
    B -->|Install| C[Installation Issues]
    B -->|Test| D[Test Failures]
    B -->|Import| E[Import Errors]
    B -->|Build| F[Build/Package Issues]
    B -->|CI/CD| G[Pipeline Failures]

    C --> H[Check Dependencies]
    D --> I[Check Coverage]
    E --> J[Check Python Path]
    F --> K[Check uv Config]
    G --> L[Check Logs]

    style A fill:#ffebee
    style H fill:#e3f2fd
    style I fill:#e3f2fd
    style J fill:#e3f2fd
    style K fill:#e3f2fd
    style L fill:#e3f2fd
```

## 🛠️ Common Issues

### Installation Problems

<details>
<summary><b>uv sync fails</b></summary>

**Symptoms:**
- `No pyproject.toml found`
- `SolverProblemError`
- Dependency conflicts

**Solutions:**

1. **Ensure you're in the project root:**
   ```bash
   ls pyproject.toml  # Should show the file
   ```

2. **Update uv:**
   ```bash
   # Update uv via installer (see https://docs.astral.sh/uv/)
   ```

3. **Clear cache and retry:**
   ```bash
   uv cache clean
   uv sync
   ```

4. **For dependency conflicts:**
   ```bash
   uv lock
   uv sync
   ```
</details>

<details>
<summary><b>Pre-commit hooks fail to install</b></summary>

**Symptoms:**
- `pre-commit: command not found`
- Hooks not running on commit

**Solutions:**

1. **Install pre-commit:**
   ```bash
   uv sync
   uv run pre-commit install
   ```

2. **Verify installation:**
   ```bash
   uv run pre-commit --version
   cat .git/hooks/pre-commit  # Should exist
   ```

3. **Manual run:**
   ```bash
   uv run pre-commit run --all-files
   ```
</details>

### Test Failures

<details>
<summary><b>Tests fail locally but pass in CI</b></summary>

**Common causes:**
- Different Python versions
- Missing test dependencies
- Environment variables
- Timezone differences

**Debug steps:**

1. **Check Python version:**
   ```bash
   python --version  # Should match CI
   uv venv
   ```

2. **Install all dependencies:**
   ```bash
   uv sync --group security --group compliance
   ```

3. **Run specific test:**
   ```bash
   uv run pytest tests/unit/test_specific.py -v
   ```

4. **Check environment:**
   ```bash
   uv run pytest --collect-only  # List all tests
   uv run pytest -m "not ci_only"  # Skip CI-only tests
   ```
</details>

<details>
<summary><b>Coverage below threshold</b></summary>

**Symptoms:**
- `FAILED: Coverage only 85%, need 90%`

**Solutions:**

1. **Generate coverage report:**
   ```bash
   uv run pytest --cov=src --cov-report=html
   open htmlcov/index.html  # View in browser
   ```

2. **Find uncovered lines:**
   ```bash
   uv run pytest --cov=src --cov-report=term-missing
   ```

3. **Common missing coverage:**
   - Exception handlers
   - CLI error paths
   - Optional imports
   - Type checking blocks

4. **Add tests for missing coverage:**
   ```python
   # Test exception handling
   def test_error_handling():
       with pytest.raises(ValueError):
           function_that_should_fail()

   # Test CLI errors
   def test_cli_invalid_input(runner):
       result = runner.invoke(cli, ['--invalid'])
       assert result.exit_code != 0
   ```
</details>

### Import Errors

<details>
<summary><b>Module not found errors</b></summary>

**Symptoms:**
- `ModuleNotFoundError: No module named 'augint_library'`
- Import works in some places but not others

**Solutions:**

1. **Install in development mode:**
   ```bash
   uv sync
   ```

2. **Check Python path:**
   ```python
   import sys
   print(sys.path)
   # Should include project directory
   ```

3. **Verify package structure:**
   ```bash
   ls src/augint_library/__init__.py  # Must exist
   ls src/augint_library/py.typed     # For type hints
   ```

4. **For tests, ensure pytest is finding the package:**
   ```bash
   uv run python -c "import augint_library; print(augint_library.__file__)"
   ```
</details>

### Build Issues

<details>
<summary><b>Package build fails</b></summary>

**Symptoms:**
- `uv build` fails
- Missing files in distribution

**Solutions:**

1. **Check package configuration:**
   ```toml
   # pyproject.toml
   [project]
   packages = [{include = "augint_library", from = "src"}]
   ```

2. **Verify all files are included:**
   ```bash
   uv build
   tar -tf dist/*.tar.gz | head -20  # List files in package
   ```

3. **Clean and rebuild:**
   ```bash
   rm -rf dist/
   uv build -v  # Verbose output
   ```
</details>

### CI/CD Pipeline Issues

<details>
<summary><b>GitHub Actions failing</b></summary>

**Common failures and solutions:**

1. **Linting errors:**
   ```bash
   # Fix locally before pushing
   make lint
   make format
   ```

2. **Type checking errors:**
   ```bash
   uv run mypy src/
   ```

3. **Security scan failures:**
   ```bash
   uv run bandit -r src/
   uv run safety check
   uv run pip-audit
   ```

4. **Check specific job logs:**
   - Go to Actions tab in GitHub
   - Click on failed workflow
   - Expand failed step
   - Look for specific error message
</details>

<details>
<summary><b>Publishing to PyPI fails</b></summary>

**Symptoms:**
- `403 Forbidden` errors
- `Invalid or non-existent authentication`

**Solutions:**

1. **For trusted publishing (recommended):**
   - Ensure GitHub environment is configured
   - Check repository name matches PyPI
   - Verify OIDC is set up correctly

2. **For token-based publishing:**
   ```bash
   # Test with TestPyPI first
   uv publish --publish-url https://test.pypi.org/legacy/
   ```

3. **Version conflicts:**
   - Ensure version is bumped
   - Check version doesn't already exist on PyPI
</details>

## 🔧 Debug Commands

### Information Gathering

```bash
# System information
uv venv
python --version
uv --version

# Project state
git status
git log --oneline -5
uv tree

# Test environment
uv run pytest --version
uv run python -m pytest --markers

# Coverage details
uv run coverage report
uv run coverage html
```

### Reset Commands

```bash
# Clean everything
make clean
rm -rf .venv/
uv sync

# Reset git hooks
pre-commit uninstall
pre-commit install

# Clear caches
uv cache clean
pytest --cache-clear
```

## 📊 Performance Issues

### Slow Tests

```mermaid
graph TD
    A[Slow Tests] --> B{Cause?}
    B -->|I/O| C[Mock External Calls]
    B -->|CPU| D[Profile Code]
    B -->|Memory| E[Reduce Test Data]

    C --> F[Use pytest-mock]
    D --> G[Use pytest-benchmark]
    E --> H[Use generators]

    style A fill:#ffebee
    style F fill:#e8f5e9
    style G fill:#e8f5e9
    style H fill:#e8f5e9
```

**Solutions:**

1. **Run tests in parallel:**
   ```bash
   uv run pytest -n auto
   ```

2. **Skip slow tests locally:**
   ```bash
   uv run pytest -m "not slow"
   ```

3. **Profile slow tests:**
   ```bash
   uv run pytest --durations=10
   ```

## 🆘 Getting Help

### Before Asking for Help

1. **Check existing issues:**
   - [GitHub Issues](https://github.com/svange/augint-library/issues)
   - Search for your error message

2. **Gather information:**
   ```bash
   # Create diagnostic report
   uv venv > diagnostic.txt
   uv tree >> diagnostic.txt
   uv run pytest --version >> diagnostic.txt
   ```

3. **Try minimal reproduction:**
   - Create smallest example that shows the problem
   - Remove unrelated code
   - Test in clean environment

### Where to Get Help

- **GitHub Issues**: For bugs and feature requests
- **Discussions**: For questions and help
- **Stack Overflow**: Tag with `augint-library`

### Reporting Bugs

Include:
1. Python version and OS
2. Full error message and traceback
3. Minimal code to reproduce
4. What you expected vs what happened
5. What you've already tried

## 🔗 Related Guides

- [Setup Issues](./setup-issues.md)
- [Testing Issues](./testing-issues.md)
- [Import Errors](./import-errors.md)
- [Windows-Specific Issues](../development/troubleshooting/claude-code-windows.md)
