typthon/STRICT_TYPING.md

# Typthon Strict Typing Vision

## Overview

Typthon aims to be a strictly typed variant of Python, bringing compile-time type safety while maintaining Python's readable syntax and developer-friendly features.

## Current Status

**Foundation Phase: Complete** ✅
- Renamed all Py* → Ty* prefixes throughout codebase
- Build system fully functional
- Core interpreter operational
- Ready for type system enhancements

## Goals

### Short Term
1. **Type Annotation Enforcement**
   - Make type hints mandatory for function signatures
   - Require explicit types for class attributes
   - Enforce type annotations at module level

2. **Compile-Time Type Checking**
   - Implement static analysis during compilation
   - Catch type errors before runtime
   - Provide helpful error messages with suggestions

3. **Type Inference**
   - Infer types where obvious from context
   - Reduce annotation burden for local variables
   - Maintain strictness at API boundaries

### Long Term
1. **Advanced Type Features**
   - Generic types with variance
   - Union and intersection types
   - Literal types
   - Protocol types (structural subtyping)

2. **Performance Optimizations**
   - Use type information for optimization
   - Eliminate runtime type checks where proven safe
   - Generate specialized code paths

3. **Gradual Typing Integration**
   - Interoperate with Python libraries
   - Provide clear boundaries between typed/untyped code
   - Support progressive migration from Python

## Design Principles

1. **Safety First**
   - Type errors should be caught at compile time
   - No implicit type conversions that lose information
   - Null safety (no implicit None)

2. **Developer Friendly**
   - Clear, actionable error messages
   - Minimal annotation burden where types are obvious
   - Helpful IDE integration

3. **Python Compatible (Where Possible)**
   - Maintain Python syntax for familiarity
   - Support Python libraries with typed wrappers
   - Enable gradual migration path

4. **Performance Conscious**
   - Use type information to generate faster code
   - Eliminate unnecessary runtime checks
   - Enable AOT compilation opportunities

## Proposed Syntax

### Mandatory Function Annotations
```python
# ✅ Valid Typthon
def add(x: int, y: int) -> int:
    return x + y

# ❌ Error: Missing type annotations
def add(x, y):
    return x + y
```

### Type Inference for Locals
```python
def process_data(items: list[int]) -> int:
    # Type inferred as int
    total = 0
    
    # Type inferred as int from iteration
    for item in items:
        total += item
    
    return total
```

### Null Safety
```python
from typing import Optional

# Explicit Optional required for nullable values
def find_user(id: int) -> Optional[User]:
    ...

# Must handle None case
user = find_user(42)
if user is not None:
    print(user.name)  # ✅ Safe
else:
    print("Not found")

# ❌ Error: user might be None
print(user.name)
```

## Implementation Plan

### Phase 1: Type Analysis Infrastructure
- [ ] Build AST analyzer for type annotations
- [ ] Implement type representation system
- [ ] Create type compatibility checker
- [ ] Add error reporting framework

### Phase 2: Basic Type Checking
- [ ] Enforce function signature types
- [ ] Check variable assignments
- [ ] Validate return types
- [ ] Implement basic type inference

### Phase 3: Advanced Features
- [ ] Generic type support
- [ ] Protocol types
- [ ] Union/Intersection types
- [ ] Type narrowing

### Phase 4: Optimizations
- [ ] Use types for code generation
- [ ] Eliminate redundant checks
- [ ] Enable specialization
- [ ] AOT compilation support

## Compatibility with Python

### Python Library Usage
```python
# Import Python libraries with typed stubs
from typing_extensions import TypedDict
import numpy as np  # With .pyi stub file

# Or use explicit typing at boundary
def process_numpy(arr: np.ndarray[np.float64]) -> float:
    return float(np.mean(arr))  # Explicit cast
```

### Migration Path
1. Start with type stubs for Python libraries
2. Gradually add type annotations to code
3. Enable strict checking per-module
4. Full type safety at boundaries

## Benefits

1. **Fewer Bugs** - Catch errors before they reach production
2. **Better Documentation** - Types serve as always-up-to-date documentation
3. **IDE Support** - Better autocomplete, refactoring, navigation
4. **Performance** - Enable optimizations not possible with dynamic types
5. **Confidence** - Refactor fearlessly with type checking

## References

- Python typing PEPs (PEP 484, 526, 544, 585, 604, 612)
- MyPy static type checker
- TypeScript's approach to gradual typing
- Rust's type system for inspiration on safety
- Swift's type inference strategy

## Contributing

Type system design is an ongoing discussion. See:
- GitHub Issues with `type-system` label
- Design discussions in `/docs/design/`
- Implementation RFCs

---

**Note**: This is a living document. The type system design will evolve as we implement and learn. Community feedback is essential to making Typthon both powerful and practical.