Refactoring 06: Static Analysis and Style

Goal

Improve maintainability with consistent formatting, linting, and basic type checking.

Sequence

• Order: 06
• Previous: refactoring-05-testing-regression
• Next: refactoring-07-documentation-usage

Workflow

• Detect existing formatters and linters; extend their configs instead of replacing.
  • Success: Existing tooling remains primary with minimal config changes.
• If none exist, propose a minimal toolchain (for example: ruff + black).
  • Success: A small, documented toolchain is selected.
• Fix warnings in touched code first; avoid mass rewrites unless requested.
  • Success: Touched files are clean without broad rewrites.
• Add type hints to public functions and core data structures.
  • Success: Public APIs have basic type annotations.
• Run checks via uv run to use the repo environment.
  • Success: Checks execute successfully through uv run.

Guardrails

• Avoid noisy lint rules that block iteration.
• Keep formatting changes separate from logic changes when possible.
• Prefer gradual typing over strict project wide enforcement.