Add type hints propagation and mypy/radon to CI

[marota]

Summary

This PR completes the type-hints rollout across the alphaDeesp codebase and integrates static type checking and code quality metrics into the CircleCI pipeline.

Key Changes

Type Hints Propagation

• Added signature-level type annotations to six previously untyped modules:
  • core/alphadeesp.py (~38 signatures)
  • core/graphsAndPaths.py (~76 signatures)
  • core/network.py (3 key signatures + attributes)
  • core/printer.py (7 methods/functions)
  • core/grid2op/Grid2opSimulation.py (~33 signatures)
  • core/pypownet/PypownetSimulation.py (~27 signatures)
• Type-annotated function count increased from 36 to ~220 return-type annotations
• Added base-class-level attribute annotations on Simulation (param_options, debug) to support strict-mode checking in seed modules
• Used Any pragmatically for backend-specific objects (Grid2op observations, pypownet environments, rustworkx graphs) where precise types are unavailable
• No semantic changes or refactors—only def signatures and typing imports were modified

Mypy Integration in CI

• Added mypy --ignore-missing-imports to CircleCI build-and-test job
• Two-stage type checking:
  • Strict mode for seed modules (core/simulation.py, core/elements.py) — failures block the build
  • Permissive mode for remaining modules — informational only (|| true guard)
• Configuration in setup.cfg with per-module overrides
• Excludes legacy Pypownet backend, optional toolbox scripts, and resource files to match existing CI scope
• Current status: 0 errors in strict scope, ~51 errors in permissive scope (mostly local variable annotations and int/float assignments in hot loops)

Code Quality Metrics in CI

• Added radon step to CircleCI for automated code quality reporting:
  • Cyclomatic complexity (A-F grades, minimum C threshold)
  • Maintainability Index (per-module tracking)
  • Raw metrics (SLOC, comment ratio, blank-line ratio)
• All radon commands guarded with || true — purely informational, never fails the build
• Replaces manual local radon invocations documented in the analysis guide

Documentation Updates

• Updated docs/code-quality-analysis.md with:
  • New "Type hints propagation" section detailing annotation strategy and module-by-module coverage
  • New "Mypy in CI" section explaining strict/permissive configuration and current status
  • New "Code quality metrics in CI" section documenting radon integration
  • Updated metrics table: type-annotated functions now at ~220 (was 36)
  • Marked items 14 (type hints + mypy) as done with branch reference

Implementation Details

• Guidelines for propagation: preferred Any over guessing for backend objects; used networkx.MultiDiGraph, pandas.DataFrame, Sequence[float] for clear contracts; propagated abstract-base-class return types to concrete backends for Liskov-style checks
• Mutable defaults were not rewritten in this pass (tracked separately)
• ignore_missing_imports = True silences stubs from grid2op, lightsim2grid, networkx, rustworkx, pypowsybl
• follow_imports = silent prevents permissive run from cascading into strict-scope errors

https://claude.ai/code/session_0173Le82Tq8axHhYJWfEBCgD