Add comprehensive pre-commit hooks for local development (#26)

* docs: add comprehensive Google-style docstrings to all public APIs (#24)

Added comprehensive API documentation following Google-style docstring format:

- python/dioxide/__init__.py: Enhanced module docstring with quick start example
- python/dioxide/scope.py: Detailed Scope enum docs with usage examples
- python/dioxide/decorators.py: Complete @component decorator documentation
- python/dioxide/container.py: Comprehensive Container class documentation

All public methods now include:
- Clear description of purpose and behavior
- Args with types and detailed explanations
- Returns with type information
- Raises documenting exceptions
- Working, tested examples
- Usage notes and best practices

Documentation features:
- All examples are executable and tested
- Type hints match docstring descriptions
- IDE autocomplete shows full documentation
- help() function displays useful information
- Examples demonstrate common use cases

This completes issue #24 - Complete API Documentation

* feat: add comprehensive pre-commit hooks configuration (#25)

This commit adds a complete pre-commit hooks configuration that matches CI checks:

Changes:
- Updated .pre-commit-config.yaml with latest hook versions
- Python checks: ruff format, ruff check --fix, isort, mypy --strict
- Rust checks: cargo fmt, cargo clippy with strict flags
- General checks: trailing whitespace, YAML/TOML validation
- Updated CONTRIBUTING.md with comprehensive pre-commit documentation

Technical notes:
- Tests are not included in pre-commit hooks due to uv/maturin interaction
- uv run reinstalls packages on each invocation, breaking the Rust extension
- Developers should run tests manually: uv run pytest tests/
- Hooks run in < 5 seconds for fast local development

Closes #25

* style: apply ruff formatting to Python files

These files were reformatted by ruff during pre-commit hook setup.
No functional changes.

Author: mikelane

.pre-commit-config.yaml

@@ -1,6 +1,7 @@
 repos:
+  # General file hygiene
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.5.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
@@ -10,48 +11,59 @@ repos:
       - id: check-merge-conflict
       - id: mixed-line-ending
 
+  # Python formatting and linting (must match CI exactly)
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.15
+    rev: v0.14.3
     hooks:
       - id: ruff
         args: [--fix, --unsafe-fixes]
+        files: ^(python/|tests/)
       - id: ruff-format
+        files: ^(python/|tests/)
 
+  # Import sorting
   - repo: https://github.com/pycqa/isort
-    rev: 5.13.2
+    rev: 7.0.0
     hooks:
       - id: isort
         args: [--profile=black, --line-length=120]
+        files: ^(python/|tests/)
 
+  # Type checking (strict mode to match CI)
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.8.0
+    rev: v1.18.2
     hooks:
       - id: mypy
         additional_dependencies: [pytest>=8.0]
-        args: [--python-version=3.11]
+        args: [--strict, --config-file=pyproject.toml]
+        files: ^(python/|tests/)
         exclude: ^features/
 
+  # Rust formatting and linting (local hooks)
   - repo: local
     hooks:
       - id: cargo-fmt
         name: cargo fmt
-        entry: cargo fmt
+        entry: bash -c 'cd rust && cargo fmt --all --check'
         language: system
         types: [rust]
         pass_filenames: false
 
       - id: cargo-clippy
         name: cargo clippy
-        entry: cargo clippy
+        entry: bash -c 'cd rust && cargo clippy --all-targets --all-features -- -D warnings -A non-local-definitions'
         language: system
         types: [rust]
         pass_filenames: false
-        args: [--all-targets, --all-features, --, -D, warnings, -A, non-local-definitions]
 
-      - id: pytest-cov
-        name: pytest with coverage
-        entry: uv run pytest
-        language: system
-        types: [python]
-        pass_filenames: false
-        args: [tests/, --cov=dioxide, --cov-fail-under=95, --cov-branch, -q]
+      # NOTE: Tests are intentionally NOT included in pre-commit hooks.
+      # Reason: The Rust extension requires maturin build, but `uv run` reinstalls
+      # packages on each invocation, which undoes the maturin-built extension.
+      # This creates a chicken-and-egg problem that significantly slows down commits.
+      #
+      # Developer workflow:
+      # 1. Pre-commit catches linting/formatting issues (< 5 seconds)
+      # 2. Run tests manually: `uv run pytest tests/` (< 10 seconds)
+      # 3. CI runs full test suite on push
+      #
+      # This keeps local commits fast while ensuring quality via CI.

CONTRIBUTING.md

@@ -18,8 +18,8 @@ Be respectful, inclusive, and professional. We're all here to build something us
    ```bash
    uv venv
    source .venv/bin/activate
-   uv pip install -e ".[dev]"
-   maturin develop
+   uv sync --all-extras
+   uv run maturin develop
    pre-commit install
    ```
 
@@ -40,22 +40,24 @@ Be respectful, inclusive, and professional. We're all here to build something us
 
 2. **Write tests first** (TDD approach):
    - Add failing tests in `tests/`
-   - Run `pytest` to confirm they fail
+   - Run `uv run pytest tests/` to confirm they fail
    - Implement the feature
-   - Run `pytest` to confirm they pass
+   - Run `uv run pytest tests/` to confirm they pass
 
-3. **Follow code style**:
-   - Python: Single quotes, vertical hanging indent for imports
-   - Rust: Standard `rustfmt` style
-   - Run `tox -e format` to auto-format
-   - Run `tox -e lint` to check
+3. **Pre-commit hooks will automatically**:
+   - Format Python code (ruff format)
+   - Fix linting issues (ruff check --fix)
+   - Sort imports (isort)
+   - Check types (mypy --strict)
+   - Format Rust code (cargo fmt)
+   - Lint Rust code (cargo clippy)
 
-4. **Type check**:
+4. **Run tests before pushing**:
    ```bash
-   tox -e type
+   uv run pytest tests/ --cov=dioxide --cov-branch
    ```
 
-5. **Run full test suite**:
+5. **Run full quality checks** (optional, CI will run these):
    ```bash
    tox
    ```
@@ -70,6 +72,54 @@ Be respectful, inclusive, and professional. We're all here to build something us
   - `test: Add tests for shutdown lifecycle`
   - `refactor: Simplify graph construction logic`
 
+### Pre-commit Hooks
+
+Pre-commit hooks run automatically when you commit, catching issues before they reach CI.
+
+**What hooks do**:
+- ✅ Format Python code (ruff format)
+- ✅ Auto-fix linting issues (ruff check --fix --unsafe-fixes)
+- ✅ Sort imports (isort)
+- ✅ Type check (mypy --strict)
+- ✅ Format Rust code (cargo fmt)
+- ✅ Lint Rust code (cargo clippy)
+- ✅ Check YAML/TOML syntax
+- ✅ Remove trailing whitespace
+
+**Installation**:
+```bash
+pre-commit install
+```
+
+**Running manually**:
+```bash
+# Run all hooks on all files
+pre-commit run --all-files
+
+# Run specific hook
+pre-commit run ruff --all-files
+
+# Update hook versions
+pre-commit autoupdate
+```
+
+**Bypassing hooks** (use sparingly):
+```bash
+# Skip hooks for WIP commits
+git commit --no-verify -m "WIP: work in progress"
+```
+
+**Performance**:
+- Hooks run in < 5 seconds for incremental commits
+- First run may take longer (installing hook environments)
+
+**Note on tests**:
+Tests are NOT run in pre-commit hooks due to technical limitations with the Rust extension build.
+Always run tests manually before pushing:
+```bash
+uv run pytest tests/ --cov=dioxide --cov-branch
+```
+
 ### Pull Request Process
 
 1. **Update documentation** if needed (README, docstrings, etc.)

tests/test_type_safety.py

@@ -1,6 +1,5 @@
 """Runtime tests for type safety and type inference."""
 
-
 from dioxide import Container, Scope, component
 
 

tests/type_checking/test_mypy_catches_errors.py

@@ -46,14 +46,14 @@ def it_catches_invalid_resolve_usage(self) -> None:
             output = result.stdout + result.stderr
 
             # Should catch attr-defined errors
-            assert (
-                'has no attribute' in output or 'attr-defined' in output
-            ), f'mypy should catch attribute errors\nOutput: {output}'
+            assert 'has no attribute' in output or 'attr-defined' in output, (
+                f'mypy should catch attribute errors\nOutput: {output}'
+            )
 
             # Should catch arg-type errors
-            assert (
-                'Argument' in output or 'arg-type' in output
-            ), f'mypy should catch argument type errors\nOutput: {output}'
+            assert 'Argument' in output or 'arg-type' in output, (
+                f'mypy should catch argument type errors\nOutput: {output}'
+            )
 
         finally:
             # Clean up temp file