> ## Documentation Index
> Fetch the complete documentation index at: https://docs.myspellchecker.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Guide for developers working on mySpellChecker.

This section covers environment setup, testing workflows, Cython development, and contribution guidelines for the mySpellChecker project.

## Contents

### Getting Started

* **[Setup](/development/setup)** - Development environment setup
* **[Architecture](/architecture/index)** - System architecture

### Development Workflow

* **[Testing](/development/testing)** - Running and writing tests
* **[Cython Development](/development/cython-guide)** - Working with Cython modules

### Contributing

* **[Contributing Guide](/development/contributing)** - How to contribute

## Quick Start

### Environment Setup

```bash theme={null}
# Clone repository
git clone https://github.com/thettwe/myspellchecker.git
cd my-spellchecker

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

# Build Cython extensions
python setup.py build_ext --inplace
```

### Running Tests

```bash theme={null}
# All tests
pytest tests/

# With coverage
pytest tests/ --cov=myspellchecker

# Specific test file
pytest tests/test_syllable_rules.py

# By marker
pytest tests/ -m unit
pytest tests/ -m integration
```

### Code Quality

```bash theme={null}
# Format code
ruff format .

# Lint code
ruff check .

# Type checking
mypy src/myspellchecker
```

## Project Structure

<Tree>
  <Tree.Folder name="myspellchecker" defaultOpen>
    <Tree.Folder name="src/myspellchecker" defaultOpen>
      <Tree.Folder name="core" />

      <Tree.Folder name="algorithms" />

      <Tree.Folder name="commands" />

      <Tree.Folder name="providers" />

      <Tree.Folder name="data_pipeline" />

      <Tree.Folder name="segmenters" />

      <Tree.Folder name="tokenizers" />

      <Tree.Folder name="text" />

      <Tree.Folder name="training" />

      <Tree.Folder name="grammar" />

      <Tree.Folder name="rules" />

      <Tree.Folder name="schemas" />

      <Tree.Folder name="data" />

      <Tree.Folder name="utils" />
    </Tree.Folder>

    <Tree.Folder name="tests" defaultOpen>
      <Tree.Folder name="integration" />

      <Tree.Folder name="e2e" />

      <Tree.Folder name="fixtures" />

      <Tree.File name="test_*.py" />
    </Tree.Folder>

    <Tree.Folder name="scripts" />
  </Tree.Folder>
</Tree>

## Development Guidelines

### Code Style

* Follow PEP 8 with 100-character line length
* Use type hints for all public functions
* Write docstrings for all public APIs
* Use meaningful variable and function names

### Testing

* Maintain ≥75% code coverage
* Write unit tests for all new functions
* Add integration tests for new features
* Use pytest fixtures for test data

### Documentation

* Update documentation for all changes
* Include docstrings with examples
* Add entries to CHANGELOG.md

### Git Workflow

```bash theme={null}
# Create feature branch
git checkout -b feature/my-feature

# Make changes and commit
git add .
git commit -m "feat: add my feature"

# Push and create PR
git push origin feature/my-feature
```

### Commit Messages

Follow conventional commits:

* `feat:` New feature
* `fix:` Bug fix
* `docs:` Documentation
* `test:` Tests
* `refactor:` Refactoring
* `perf:` Performance
* `chore:` Maintenance

## Key Components

### Core Components

| Component           | Location               | Purpose               |
| ------------------- | ---------------------- | --------------------- |
| SpellChecker        | `core/spellchecker.py` | Main entry point      |
| SpellCheckerBuilder | `core/builder.py`      | Fluent configuration  |
| Validators          | `core/validators/`     | Validation layers     |
| Config              | `core/config/`         | Configuration package |

### Algorithms

| Algorithm | Location                              | Purpose            |
| --------- | ------------------------------------- | ------------------ |
| SymSpell  | `algorithms/symspell.py`              | Fast suggestions   |
| N-gram    | `algorithms/ngram_context_checker.py` | Context validation |
| Viterbi   | `algorithms/viterbi.pyx`              | POS tagging        |

### Cython Modules

| Module            | Location                                  | Purpose             |
| ----------------- | ----------------------------------------- | ------------------- |
| normalize\_c      | `text/normalize_c.pyx`                    | Fast normalization  |
| edit\_distance\_c | `algorithms/distance/edit_distance_c.pyx` | Edit distance       |
| batch\_processor  | `data_pipeline/batch_processor.pyx`       | Parallel processing |

## Cython Development

### Building Extensions

```bash theme={null}
# Rebuild after changes
python setup.py build_ext --inplace

# Clean build
rm -rf build/ src/myspellchecker/**/*.cpp src/myspellchecker/**/*.so
python setup.py build_ext --inplace
```

### Cython Tips

1. **Profile first**: Only optimize hot paths
2. **Use typed memoryviews**: For array operations
3. **Release GIL**: For parallel operations
4. **Provide fallbacks**: Pure Python for compatibility

### Example Cython Pattern

Not all Cython modules use the same import pattern:

**normalize.py** requires Cython directly (no fallback):

```python theme={null}
# normalize.py imports Cython extension unconditionally
from myspellchecker.text.normalize_c import (
    remove_zero_width_chars as c_remove_zero_width,
    reorder_myanmar_diacritics as c_reorder_diacritics,
)
```

**viterbi.py** has a Python fallback via flag:

```python theme={null}
# viterbi.py uses try/except with a flag
try:
    from myspellchecker.algorithms import viterbi_c
    _HAS_CYTHON_VITERBI = True
except ImportError:
    _HAS_CYTHON_VITERBI = False
```

## Testing Guide

### Test Categories

```python theme={null}
# Unit test
@pytest.mark.unit
def test_syllable_rules():
    assert is_valid_syllable("မြန်")

# Integration test
@pytest.mark.integration
def test_full_pipeline():
    checker = SpellChecker()
    result = checker.check("test text")
    assert result is not None

# Slow test
@pytest.mark.slow
def test_large_corpus():
    # Long-running test
    pass
```

### Running Specific Tests

```bash theme={null}
# By marker
pytest -m unit
pytest -m "not slow"

# By name
pytest -k "syllable"

# Single file
pytest tests/test_syllable_rules.py

# Single test
pytest tests/test_syllable_rules.py::test_valid_syllable
```

### Test Fixtures

```python theme={null}
# conftest.py
@pytest.fixture
def spell_checker():
    """Create a SpellChecker instance."""
    return SpellChecker()

@pytest.fixture
def sample_text():
    """Sample Myanmar text."""
    return "မြန်မာစာ"
```

## Debugging

### Enable Debug Logging

```python theme={null}
from myspellchecker.utils.logging_utils import configure_logging
configure_logging(level="DEBUG")
```

### Using Debugger

```python theme={null}
# Add breakpoint
import pdb; pdb.set_trace()

# Or use VS Code debugger
```

### Common Issues

| Issue             | Debugging Approach        |
| ----------------- | ------------------------- |
| Wrong suggestions | Check SymSpell parameters |
| Slow performance  | Profile with cProfile     |
| Memory issues     | Use memory\_profiler      |
| Cython errors     | Check .pyx compilation    |

## Benchmarking

### Test Fixtures

Test datasets are located in `tests/fixtures/benchmarks/`:

* `pos_gold_standard.json` - POS tagging accuracy evaluation

See test fixtures for sample evaluation data.

## Release Process

### Version Bump

```bash theme={null}
# Update version in pyproject.toml
# Update CHANGELOG.md
git add .
git commit -m "chore: bump version to X.Y.Z"
git tag vX.Y.Z
git push origin main --tags
```

### Building Package

```bash theme={null}
# Build distribution
python -m build

# Check package
twine check dist/*

# Upload to PyPI
twine upload dist/*
```

## Resources

### Documentation

* [Architecture](/architecture/index)
* [API Reference](/api-reference/index)
* [Configuration](/guides/configuration)

### External Links

* [Python Packaging Guide](https://packaging.python.org/)
* [Cython Documentation](https://cython.readthedocs.io/)
* [pytest Documentation](https://docs.pytest.org/)