Modernize API with .update(), freeze/MISSING, and type coercion (#3)

* Remove CLI module in favor of manual parsing pattern

Remove the built-in CLI parsing utilities (`Config.from_cli()`, `parse_override()`, `parse_overrides()`) to simplify the library and encourage users to handle their own argument parsing with standard libraries like argparse, click, typer, or fire.

**Why:**
- Reduces library complexity and maintenance burden
- Users have full control over CLI behavior and flags
- Works better with diverse CLI frameworks
- The recommended pattern is simple: just 3 lines of code for basic CLI override parsing

**Migration path:**
```python
# Old way
config = Config.from_cli("config.yaml", sys.argv[1:])

# New way (3 lines)
config = Config()
config.update("config.yaml")
for arg in sys.argv[1:]:
    if "=" in arg:
        key, value = arg.split("=", 1)
        try:
            value = ast.literal_eval(value)
        except (ValueError, SyntaxError):
            pass
        config.set(key, value)
```

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Add type coercion system for schema validation

Introduce automatic type coercion to convert compatible types during validation, making configs more flexible and user-friendly.

**Features:**
- String to numeric conversion (`"123"` → `123`, `"3.14"` → `3.14`)
- Numeric type conversion (`1` → `1.0` for float fields)
- String to bool parsing (`"true"`, `"yes"`, `"1"` → `True`)
- List/tuple interconversion
- Dict to dataclass conversion (nested structures)
- Preserves None values and handles Optional types correctly

**Example:**
```python
@DataClass
class Config:
    port: int
    rate: float

config = Config()
config.update({"port": "8080", "rate": "0.5"})  # Strings coerced!
config.validate(Config)  # ✓ Works! port=8080, rate=0.5
```

**Implementation:**
- `coerce_value()`: Core coercion logic with recursive support
- Smart type detection and conversion with fallback to original value
- Integration with `_validate_field()` in schema.py

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Enhance config API with freeze/unfreeze and MISSING support

Add advanced configuration features for better control and partial config support.

**New Features:**

1. **Frozen Configs** - Prevent mutations after initialization:
   ```python
   config.freeze()  # Lock config
   config.set("key", "value")  # Raises FrozenConfigError
   config.unfreeze()  # Allow mutations again
   ```

2. **MISSING Sentinel** - Support partial configs with required-but-not-yet-set values:
   ```python
   config = Config(allow_missing=True)
   config.update({"api_key": MISSING})  # Placeholder for later
   config.set("api_key", os.getenv("API_KEY"))  # Fill in
   config.validate(schema)  # Ensure complete (allow_missing=False by default)
   ```

3. **Continuous Validation** - Validate on every mutation when schema provided:
   ```python
   config = Config(schema=MySchema)  # Enable continuous validation
   config.update(data)  # Validates immediately!
   config.set("port", "invalid")  # Raises ValidationError
   ```

**API Changes:**
- Add `freeze()`, `unfreeze()`, `is_frozen()` methods
- Add `MISSING` sentinel constant
- Add `allow_missing` parameter to `Config()` and `validate()`
- Integrate type coercion into validation pipeline
- Enhanced error messages with field paths

**Tests:**
- Comprehensive test coverage for freeze/unfreeze behavior
- MISSING sentinel edge cases
- Continuous validation scenarios
- Updated existing tests for new API patterns

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Comprehensive documentation updates for v0.0.5

Update all documentation to reflect the new API design, removed CLI module, and new features (type coercion, freeze/unfreeze, MISSING sentinel).

**Major Changes:**

1. **Installation Guide** (`installation.md`):
   - Simplified just installation instructions (use package managers)
   - Removed optional dependencies section (minimal deps by design)
   - Cleaner setup instructions

2. **Quickstart Guide** (`quickstart.md`):
   - Update to new API: `Config()` + `.update()` pattern (no more `.load()`)
   - Show manual CLI override parsing (3-line pattern with ast.literal_eval)
   - Method chaining examples for cleaner code

3. **CLI Overrides** (`cli.md` - major rewrite):
   - Remove `Config.from_cli()`, `parse_override()` references
   - Show auto-detection pattern: `.update()` handles both files and overrides
   - Examples for argparse, Click, Typer, Fire
   - Manual override parsing with `parse_overrides()` for advanced use
   - Simplified mental model: just loop over args!

4. **Core User Guides**:
   - `basics.md`: Update all examples to `Config().update()` pattern
   - `operators.md`: Add composition decision flow diagram
   - `advanced.md`: Add frozen configs and MISSING sentinel sections
   - `schema-validation.md`: Document continuous validation and type coercion
   - `references.md`: Update API references

5. **Index Page** (`index.md`):
   - Update feature descriptions (continuous validation)
   - Modernize all code examples
   - Show new patterns throughout

6. **Examples Cleanup**:
   - Delete outdated examples: `simple.md`, `deep-learning.md`, `custom-classes.md`
   - Add new `quick-reference.md` with concise API overview

7. **MkDocs Config** (`mkdocs.yml`):
   - Remove examples section from navigation
   - Add quick-reference to user guide
   - Update structure for clearer organization

**Documentation Philosophy:**
- Show the simplest pattern first (Config().update())
- Encourage users to use their preferred CLI library
- Emphasize composition-by-default with explicit operators
- Highlight continuous validation benefits

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Add schema suffix to schema dataclasses in docs examples

* Improve github workflows

* Fix GitHub Actions workflows and type checking errors

Workflow Fixes:
- Fix YAML syntax in check_pull_request_title.yml
- Remove problematic types parameter (not needed with custom subjectPattern)

Type Checking Fixes (66 errors resolved):
- Keep strict mypy flags enabled (disallow_any_generics, warn_unreachable)
- Add explicit type parameters throughout (dict[str, Any], list[Any], set[Any])
- Add type annotations to helper functions (_is_union_type, etc.)
- Fix PathLike type parameter (Union[str, os.PathLike[str]])
- Add proper type hints to levenshtein_distance and ensure_tuple
- Add type assertions for dataclass field types
- Handle false positive unreachable warnings with targeted type ignores

Files modified:
- schema.py, coercion.py: Type annotations and assertions
- config.py, loader.py, items.py: Dict/list/set type parameters
- preprocessor.py, operators.py, resolver.py: Type parameters
- utils/types.py, utils/misc.py, utils/module.py: Type fixes
- errors/suggestions.py: Levenshtein distance types

All 24 source files pass strict type checking.

* Fix false mypy flag

* Add codecov.yml. Fix more mypy.

---------

Co-authored-by: Claude <[email protected]>

Author: ibro45

.codecov.yml

@@ -0,0 +1,49 @@
+# Codecov Configuration
+# Documentation: https://docs.codecov.com/docs/codecovyml-reference
+
+coverage:
+  precision: 2  # Number of decimal places (0-5)
+  round: down   # How to round coverage (down/up/nearest)
+  range: 70..100  # Color coding range (red at 70%, green at 100%)
+
+  status:
+    # Project coverage: overall repository coverage
+    project:
+      default:
+        target: 90%           # Minimum coverage threshold
+        threshold: null       # No threshold - only fail if below target
+        base: auto            # Compare against base branch
+        informational: false  # Fail the check if below target
+
+    # Patch coverage: coverage on changed lines only
+    patch:
+      default:
+        target: 80%           # New code should have at least 80% coverage
+        threshold: 0%         # No wiggle room for patch coverage
+        base: auto
+        informational: false  # Fail if new code doesn't meet target
+
+# Pull request comment configuration
+comment:
+  layout: "diff, flags, files, footer"  # What to show in PR comments
+  behavior: default                      # Comment on all PRs
+  require_changes: false                 # Comment even if coverage unchanged
+  require_base: false                    # Comment even without base report
+  require_head: true                     # Only comment if head report exists
+
+# Paths to ignore in coverage reports
+ignore:
+  - "tests/*"           # Test files
+  - "tests/**/*"        # All test subdirectories
+  - "docs/*"            # Documentation
+  - "site/*"            # Built documentation site
+  - "htmlcov/*"         # Coverage HTML reports
+  - ".venv/*"           # Virtual environment
+  - ".tox/*"            # Tox environments
+  - "**/__pycache__/*"  # Python cache
+  - "**/conftest.py"    # Pytest configuration
+  - "update_tests.py"   # Utility scripts
+
+# GitHub Checks configuration
+github_checks:
+  annotations: true  # Show coverage annotations on changed files

.github/actions/setup/action.yml

@@ -0,0 +1,28 @@
+name: 'Setup Environment'
+description: 'Setup Python with uv and install dependencies'
+inputs:
+  python-version:
+    description: 'Python version'
+    required: false
+    default: '3.12'
+  install-deps:
+    description: 'Install dependencies'
+    required: false
+    default: 'true'
+  install-groups:
+    description: 'Dependency groups to install'
+    required: false
+    default: '--all-extras --all-groups'
+runs:
+  using: 'composite'
+  steps:
+    - name: Install uv
+      uses: astral-sh/setup-uv@v6
+      with:
+        python-version: ${{ inputs.python-version }}
+        enable-cache: true
+
+    - name: Install dependencies
+      if: inputs.install-deps == 'true'
+      run: uv sync ${{ inputs.install-groups }}
+      shell: bash

.github/scripts/test_summary.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Generate GitHub Actions test summary from JUnit XML."""
+
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+
+def main() -> int:
+    """Parse JUnit XML and write summary to GitHub Actions step summary."""
+    xml_path = Path("test-results.xml")
+
+    if not xml_path.exists():
+        print("⚠️  No test results found", file=sys.stderr)
+        return 1
+
+    try:
+        tree = ET.parse(xml_path)
+        root = tree.getroot()
+
+        tests = int(root.get("tests", 0))
+        failures = int(root.get("failures", 0))
+        errors = int(root.get("errors", 0))
+        skipped = int(root.get("skipped", 0))
+        passed = tests - failures - errors - skipped
+
+        # Determine status emoji
+        if failures + errors > 0:
+            status = "❌"
+        elif skipped == tests:
+            status = "⏭️"
+        else:
+            status = "✅"
+
+        # Print summary lines
+        print(f"{status} **Test Results Summary**")
+        print(f"- ✅ Passed: {passed}")
+        print(f"- ❌ Failed: {failures}")
+        print(f"- ⚠️  Errors: {errors}")
+        print(f"- ⏭️  Skipped: {skipped}")
+        print(f"- **Total: {tests}**")
+
+        # Exit with error if tests failed
+        return 1 if (failures + errors > 0) else 0
+
+    except ET.ParseError as e:
+        print(f"❌ Failed to parse XML: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/workflows/check_pull_request_title.yml

@@ -1,35 +1,47 @@
 name: "Check PR title"
+
 on:
   pull_request:
     types: [edited, opened, synchronize, reopened]
 
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pull-requests: read
+  statuses: write
+
 jobs:
   pr-title-check:
     runs-on: ubuntu-latest
+    timeout-minutes: 5
     if: ${{ github.event.pull_request.user.login != 'allcontributors[bot]' }}
     steps:
-      # Echo the user's login
-      - name: Echo user login
-        run: echo ${{ github.event.pull_request.user.login }}
-
-      - uses: naveenk1223/action-pr-title@master
+      - uses: amannn/[email protected]
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
+          # Require imperative mood (e.g. "Add feature" not "Adds feature")
           # ^                       Start of string
           # [A-Z]                   First character must be an uppercase ASCII letter
-          # [a-zA-Z]*               Followed by zero or more ASCII letters
-          # (?<![^s]s)              Negative lookbehind: disallow a single 's' at the end of the first word
-          # ( .+)+                  At least one space and one or more characters (requires more words)
+          # [a-z]*                  Followed by zero or more lowercase letters
+          # (?<![^s]s)              Negative lookbehind: disallow single 's' at end of first word
+          # ( .+)+                  At least one space and one or more characters
           # [^.]                    Final character must not be a period
           # $                       End of string
-          regex: "^[A-Z][a-zA-Z]*(?<![^s]s)( .+)+[^.]$"
-          # Valid titles:
-          # - "Do something"
-          # - "Address something"
-          # Invalid title:
-          # - "do something"
-          # - "Do something."
-          # - "Does something"
-          # - "Do"
-          # - "Addresses something"
-          min_length: 10
-          max_length: 72
+          subjectPattern: '^[A-Z][a-z]*(?<![^s]s)( .+)+[^.]$'
+          subjectPatternError: |
+            The PR title must use imperative mood and proper formatting:
+            - Start with uppercase letter (e.g., "Add" not "add")
+            - Use base form of verb (e.g., "Add" not "Adds" or "Adding")
+            - Have multiple words (minimum 10 characters)
+            - Not end with a period
+
+            Valid: "Add new feature", "Fix bug in parser"
+            Invalid: "add feature", "Adds feature", "Add.", "Fix"
+          # Disable type prefixes (we don't use conventional commits format)
+          requireScope: false
+          ignoreLabels:
+            - ignore-title-check

.github/workflows/ci-full.yml

@@ -0,0 +1,73 @@
+name: CI Full
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  checks: write
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  tests:
+    name: Python ${{ matrix.python }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        python: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: Run all tests with coverage
+        run: |
+          uv run coverage run -m pytest tests --durations=10 \
+            --junit-xml=test-results.xml \
+            --html=test-report.html --self-contained-html
+
+      - name: Generate test summary
+        if: always()
+        run: |
+          echo "## Test Results - Python ${{ matrix.python }}" >> $GITHUB_STEP_SUMMARY
+          python3 .github/scripts/test_summary.py >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-py${{ matrix.python }}
+          retention-days: 7
+          path: |
+            test-results.xml
+            test-report.html
+            .coverage
+
+      - name: Generate coverage report
+        if: matrix.python == '3.12'
+        run: uv run coverage xml
+
+      - name: Upload coverage to Codecov
+        if: matrix.python == '3.12'
+        uses: codecov/[email protected]
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/ci.yml

@@ -0,0 +1,100 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+  checks: write
+
+env:
+  FORCE_COLOR: 1
+
+jobs:
+  quality:
+    name: ${{ matrix.check }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        check:
+          - format
+          - lint
+          - types
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup
+        with:
+          python-version: "3.12"
+          install-deps: ${{ matrix.check == 'types' && 'true' || 'false' }}
+
+      - name: Run format check
+        if: matrix.check == 'format'
+        run: uvx ruff format --diff
+
+      - name: Run lint check
+        if: matrix.check == 'lint'
+        run: uvx ruff check
+
+      - name: Run type check
+        if: matrix.check == 'types'
+        run: uv run mypy src
+
+  tests:
+    name: Tests (Python 3.12)
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: ./.github/actions/setup
+        with:
+          python-version: "3.12"
+
+      - name: Run pytest with coverage
+        run: |
+          uv run coverage run -m pytest tests --durations=10 -m "not slow" \
+            --junit-xml=test-results.xml \
+            --html=test-report.html --self-contained-html
+
+      - name: Generate test summary
+        if: always()
+        run: python3 .github/scripts/test_summary.py >> $GITHUB_STEP_SUMMARY
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-py312
+          retention-days: 7
+          path: |
+            test-results.xml
+            test-report.html
+            .coverage
+
+      - name: Generate coverage report
+        run: uv run coverage xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/[email protected]
+        with:
+          files: ./coverage.xml
+          fail_ci_if_error: true
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}