feat: Mutation caching and transitive dependency tracking

[nicklafleur]

Summary

Adds incremental mutation testing to mutmut by skipping mutants in unchanged code, with transitive invalidation via a runtime call graph. On re-runs, only mutants in functions whose source (or whose dependencies' source) changed are re-tested.

High-level

• Incremental mutation testing which cuts down mutation run duration ~linearly relative to the ratio of code changed (less code is changed, faster the run goes).
  • In practice in large codebases this means a >95% reduction in runtime on average as the amount of code not changed far outweighs the amount of code changed
  • Utility functions are particularly susceptible to "cache busting", even a noop syntactic change that modifies the AST will cause invalidation of all call chains which rely on those functions (technically correct since the code did change, but something to be aware of)
• UI support will come in a future PR

Commit Breakdown:

1. feat: add function hashing for incremental mutation testing

• Foundation: hash each function's source (SHA-256, 12 chars) and persist via hash_by_function_name on SourceFileMutationData. On subsequent runs, compare old vs. new hashes and reset mutant results to None for changed functions only.
• Introduces MutationMetadata (line number, mutation type, human-readable description) carried on every Mutation and serialized to JSON, plus an OPERATOR_TO_TYPE mapping and helpers (_determine_mutation_type, _describe_mutation).
• Tightens naming conventions (private helpers prefixed with _, MUTATION_OPERATORS constant) and adds explicit type annotations.
• New e2e_projects/benchmark_1k/ project (1000 mutants across a broad range of mutation types) with configurable delays via BENCHMARK_IMPORT_DELAY, BENCHMARK_CONFTEST_DELAY, and BENCHMARK_TEST_DELAY.

2. refactor: relocate formatting utils

• Consolidates formatting helpers previously scattered across __main__.py, file_mutation.py, and trampoline_templates.py into src/mutmut/utils/format_utils.py.
• Pure code move with no behavior change; tests updated to import from the new location.

3. feat: Add dependency tracking with function hash persistence
   • Builds the transitive invalidation layer on top of (1):
   • New MutmutState dataclass + state() singleton (state.py) consolidating old_function_hashes, current_function_hashes, and function_dependencies instead of leaking module-level globals.
   • New core.py with MutmutCallStack (backed by ContextVar for async/thread safety) and a relocated record_trampoline_hit that now records caller→callee edges during stats collection.
   • Trampoline updated to track call depth and emit dependency edges.
   • load_stats/save_stats extended to persist function_hashes and dependencies in mutmut-stats.json.
   • _cleanup_stale_stats and _invalidate_stale_dependency_edges prune state for functions that no longer exist or whose hashes changed, and transitively invalidate callers of changed callees.
   • New config options: track_dependencies and dependency_tracking_depth.
   • README/docs updated to describe the feature.

Known Issues

• Because we only track dependencies at runtime through the trampoline logic, un-mutated function are omitted in the dependency graph that is built. The call graph represents the call graph of mutated functions not the global one.
• We end up looping on all walkable files a few times, pushing time complexity higher than before. This is still a smaller penalty than the caching gain but definitely something that can be improves
• The "cache" is in the form of a json file right now, which is horrifically inefficient for the sparse reads/writes which is typical in this workfow, moving to an sqlite-based store of the state could unlock some significant storage and parallelism breakthroughs
  • I have a follow-up PR that will branch out into different forking strategies that could be extended to include easy hookups for this kind of reporting strategy.