feat: tests

Author: indietyp

libs/@local/hashql/mir/src/pass/analysis/dataflow/liveness/TEST_PLAN.md

@@ -10,6 +10,36 @@
 //! - **Kills** (removes from live set): variables that are defined
 //! - **Gens** (adds to live set): variables that are used
 //!
+//! # Analysis Variants
+//!
+//! This module provides two liveness analyses:
+//!
+//! - [`LivenessAnalysis`]: Standard liveness following the gen/kill semantics above.
+//! - [`TraversalLivenessAnalysis`]: Traversal-aware liveness that suppresses uses of a traversal
+//!   source when assigning to a known traversal destination.
+//!
+//! ## Traversal-Aware Liveness
+//!
+//! When performing traversal extraction, a source local (e.g., `entity`) may have multiple
+//! partial projections extracted into separate destination locals (e.g., `entity.uuid`,
+//! `entity.name`). Standard liveness would mark `entity` as live at every assignment to these
+//! destinations, even though only the projections are needed.
+//!
+//! [`TraversalLivenessAnalysis`] takes a [`Traversals`] reference and modifies the transfer
+//! function: when an assignment's left-hand side is a full definition of a registered traversal
+//! destination, uses of the traversal source on the right-hand side are *not* generated.
+//!
+//! ```text
+//! // Given: traversals.source() = _1, traversals.contains(_2) = true
+//! bb0:
+//!     _2 = _1.uuid   // Standard: gens _1. Traversal-aware: skips _1 (full def of _2)
+//!     _3 = _1.name   // If _3 not in traversals: gens _1 normally
+//!     return _2
+//! ```
+//!
+//! This allows dead code elimination to remove the source local when all its uses are through
+//! extracted traversals.
+//!
 //! # Example
 //!
 //! ```text
@@ -46,6 +76,14 @@ use crate::{
     visit::Visitor,
 };
 
+/// Traversal-aware liveness analysis.
+///
+/// Extends standard liveness with special handling for traversal extraction. When the left-hand
+/// side of an assignment is a full definition of a traversal destination, uses of the traversal
+/// source on the right-hand side are suppressed (not added to the live set).
+///
+/// This allows subsequent dead code elimination to remove the source local when its only uses
+/// are through extracted traversal projections.
 pub struct TraversalLivenessAnalysis<'ctx, 'heap> {
     pub traversals: &'ctx Traversals<'heap>,
 }