# HaoLine Cursor Rules

## Code Style (ALWAYS Follow)

When writing Python code:
- **Black-compliant**: 88 char line limit, double quotes, trailing commas in multi-line
- **Ruff-compliant**: No unused imports, no undefined names, proper import sorting (I, F, E, W)
- **Type hints**: Add type hints to all function signatures (args and return types)
- **Docstrings**: Google-style docstrings for public functions/classes
- **No trailing whitespace or extra blank lines at end of file**

Example function:
```python
def analyze_model(
    model_path: Path,
    hardware: str = "auto",
    precision: str = "fp32",
) -> InspectionReport:
    """Analyze a model and return inspection report.

    Args:
        model_path: Path to the ONNX model file.
        hardware: Hardware profile name or 'auto' for detection.
        precision: Precision for estimates (fp32, fp16, int8).

    Returns:
        InspectionReport with analysis results.
    """
    ...
```

## Code Quality

Before ANY commit:
1. Run `black src/haoline/` to format Python code
2. Run `ruff check src/haoline/ --fix` to fix linting issues
3. Run `mypy src/haoline/` to check types (config in pyproject.toml)
4. Verify all three pass before committing

Quick command:
```bash
black src/haoline/ && ruff check src/haoline/ --fix && mypy src/haoline/
```

### Common mypy Fixes

- **no-any-return**: Add explicit type cast or fix return type
  ```python
  # Bad: return some_dict.get("key")  # Returns Any
  # Good: return cast(str, some_dict.get("key"))
  # Or: result: str = some_dict.get("key", "")
  ```

- **assignment type mismatch**: Use correct types
  ```python
  # Bad: count: int = 1.5
  # Good: count: int = int(1.5)
  ```

- **numpy dtype issues**: Use `np.dtype` or `Any` for complex dtype expressions

## Git Workflow

- Always check `git status` before committing
- Use conventional commit messages (feat:, fix:, docs:, refactor:, test:, chore:)
- Push after committing to keep GitHub in sync

## Testing

- Run `pytest src/haoline/tests/ -v` before major changes
- CI runs on push to main - check GitHub Actions if build fails

## File Organization

- Core analysis: `src/haoline/` 
- Tests: `src/haoline/tests/`
- Format readers: `src/haoline/formats/`
- Eval import: `src/haoline/eval/`
- Docs: `README.md`, `PRD.md`, `BACKLOG.md`, `Architecture.md`, `DEPLOYMENT.md`, `PRIVACY.md`

