supercov_engine/

ruby_instrumenter.rs

//! Supercov-owned Ruby obligation discovery.
//!
//! Prism (Ruby's own parser) supplies syntax and exact byte ranges. Supercov
//! owns the denominator: every statement, method, decision and branch
//! obligation is decided here, ahead of the run, from source alone.
//!
//! Alongside the shared [`CoverageManifest`] this module emits a *probe plan*
//! for the stdlib-only Ruby runtime. Ruby's `Coverage` module already reports
//! lines, `if`/`unless`/`case`/`&.` branches and method entry with byte
//! columns, so those obligations are proven by matching its keys (shifted for
//! the text the runtime inserts). What `Coverage` cannot see — the operands of
//! `&&`/`||` for MC/DC, `||=`, loop entry, `rescue` flow and a second statement
//! on a line — is proven by probe calls the runtime splices into the source in
//! memory at load time. No insertion contains a newline, so line numbers,
//! backtraces and the stdlib line table stay exact.

use std::collections::{BTreeMap, BTreeSet};

use ruby_prism::{
    AndNode, BeginNode, CallNode, CaseMatchNode, CaseNode, DefNode, ForNode, IfNode, Location,
    Node, OrNode, RescueModifierNode, RescueNode, StatementsNode, UnlessNode, UntilNode, Visit,
    WhileNode,
};
use serde::{Deserialize, Serialize};
use serde_json::json;
use sha2::{Digest, Sha256};

use crate::{
    coverage_analysis::PointKind,
    coverage_report::{
        BranchAlternativeMeta, BranchMeta, CoverageManifest, DecisionMeta, PointMeta,
    },
};

pub const RUBY_PROBE_PLAN_VERSION: u32 = 1;
/// Global the runtime binds its probe receiver to. Chosen to be unpronounceable
/// in application code.
pub const RUBY_PROBE_RECEIVER: &str = "$__supercov";

/// Block-taking methods whose block runs once per element (or per count):
/// the idiomatic Ruby loops. Methods that may call the block zero times on a
/// non-empty receiver (`cycle`, `loop`, `lazy`) are deliberately absent.
const ITERATORS: &[&[u8]] = &[
    b"each",
    b"each_with_index",
    b"each_with_object",
    b"each_pair",
    b"each_key",
    b"each_value",
    b"each_char",
    b"each_byte",
    b"each_line",
    b"each_slice",
    b"each_cons",
    b"each_entry",
    b"each_index",
    b"reverse_each",
    b"map",
    b"collect",
    b"flat_map",
    b"collect_concat",
    b"filter_map",
    b"select",
    b"filter",
    b"reject",
    b"find",
    b"detect",
    b"find_index",
    b"find_all",
    b"all?",
    b"any?",
    b"none?",
    b"one?",
    b"count",
    b"sum",
    b"min_by",
    b"max_by",
    b"sort_by",
    b"group_by",
    b"partition",
    b"inject",
    b"reduce",
    b"take_while",
    b"drop_while",
    b"times",
    b"upto",
    b"downto",
    b"step",
];
pub const BEGIN_BODY_LIMITATION: &str = "ruby-begin-completion-unmeasured";

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum RubyInstrumenterError {
    Parse(String),
    InvalidRange,
}

impl std::fmt::Display for RubyInstrumenterError {
    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Parse(error) => write!(formatter, "Ruby parse failed: {error}"),
            Self::InvalidRange => write!(formatter, "Ruby parser returned an invalid range"),
        }
    }
}

impl std::error::Error for RubyInstrumenterError {}

/// A source span in one-based lines and zero-based byte columns, the units
/// Ruby's `Coverage` module reports. Serialized as `[[line, col], [line, col]]`.
/// What a stdlib key's span names.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase")]
pub enum KeyKind {
    /// A statement list (`then`, `else`, `when`, `in`, a loop body): Ruby
    /// spans it from its first statement's start to its last statement's
    /// end, so a probe or wrapper on its first statement becomes part of it.
    List,
    /// One expression node: a wrapper around it is a different node.
    Node,
    /// A zero-width position at the end of a predicate, which Ruby reports
    /// for an `if` without a body; it follows anything inserted up to there.
    Point,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(from = "[[usize; 2]; 2]", into = "[[usize; 2]; 2]")]
pub struct PlanSpan {
    pub start: [usize; 2],
    pub end: [usize; 2],
}

impl From<[[usize; 2]; 2]> for PlanSpan {
    fn from(value: [[usize; 2]; 2]) -> Self {
        Self {
            start: value[0],
            end: value[1],
        }
    }
}

impl From<PlanSpan> for [[usize; 2]; 2] {
    fn from(value: PlanSpan) -> Self {
        [value.start, value.end]
    }
}

/// One text insertion the runtime applies to the original source before
/// compiling it. Offsets are bytes into the original file; the runtime applies
/// insertions from the end of the file backwards, so offsets stay valid.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct Edit {
    pub offset: usize,
    pub text: String,
    /// `clause`, `statement`, `opener` or `closer`: how the insertion sits
    /// relative to the node at its offset, which decides whether keys
    /// starting or ending there move (see [`Collector::shifted`]).
    pub rank: String,
    /// The other end of the range the insertion belongs to: the end of the
    /// wrapped node or probed statement for an opener or probe, the opener's
    /// offset for a closer.
    pub scope: usize,
}

/// A `Coverage` branch key: the group type (`if`, `case`, `&.`, `while`), the
/// branch type (`then`, `else`, `when`, `in`, `body`) and the branch span in
/// post-insertion coordinates.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct StdlibKey {
    pub group: String,
    pub branch: String,
    /// What the key's span names, which decides how insertions at its edges
    /// move it (see [`Collector::shifted`]).
    pub kind: KeyKind,
    /// Span after the plan's insertions are applied.
    pub span: PlanSpan,
    /// Span in the untouched source, for interpreters that cannot apply the
    /// insertions (Ruby 3.3 does not cover code compiled by a load hook).
    pub unshifted: PlanSpan,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct StdlibDecision {
    pub id: String,
    pub value: bool,
    pub outcome: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct BranchKeyPlan {
    pub key: StdlibKey,
    /// Obligation IDs proven when this branch executed: alternatives and any
    /// statement whose first line is shared with an earlier statement.
    pub hits: Vec<String>,
    /// A single-condition decision whose vector this branch witnesses.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub decision: Option<StdlibDecision>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct MethodKeyPlan {
    pub span: PlanSpan,
    pub unshifted: PlanSpan,
    pub id: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct CaseClausePlan {
    pub key: StdlibKey,
    pub missed: String,
    pub selected: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct CaseNoMatchPlan {
    pub key: StdlibKey,
    pub matched: String,
    pub unmatched: String,
}

/// `case` clauses are tested in order, so a clause was missed exactly when a
/// later clause (or the implicit else) was selected. The runtime derives that
/// per phase from the selected counts.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct CasePlan {
    pub clauses: Vec<CaseClausePlan>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub no_match: Option<CaseNoMatchPlan>,
}

/// Short-circuit structure of a decision. Leaves are condition indexes.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(untagged)]
pub enum ConditionTree {
    Leaf(usize),
    Node {
        op: String,
        items: Vec<ConditionTree>,
        #[serde(default, skip_serializing_if = "std::ops::Not::not")]
        negate: bool,
    },
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct DerivedLogical {
    pub previous_leaves: Vec<usize>,
    pub operand_leaves: Vec<usize>,
    pub short_circuit: String,
    pub evaluated: String,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct LoopTarget {
    pub id: String,
    pub zero: String,
    pub entered: String,
    /// `until` enters the body when the predicate is falsy.
    pub until: bool,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct HandlerTarget {
    pub id: String,
    pub missed: String,
    pub selected: String,
}

/// What a probe call reports. The runtime looks the key up and records the
/// obligations named here.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "camelCase", deny_unknown_fields)]
pub enum ProbeTarget {
    /// `s(k)`: a statement sharing a line with an earlier statement ran.
    #[serde(rename_all = "camelCase")]
    Statement { id: String },
    /// `c(k, i, v)` per condition, `d(k, v)` or `w(k, v)` for the outcome.
    #[serde(rename_all = "camelCase")]
    Decision {
        id: String,
        width: usize,
        not: Vec<bool>,
        tree: ConditionTree,
        outcome_true: String,
        outcome_false: String,
        logical: Vec<DerivedLogical>,
        #[serde(rename = "loop", skip_serializing_if = "Option::is_none")]
        loop_: Option<LoopTarget>,
    },
    /// `f(k, collection)` at the loop head and `fb(k)` as the first body statement.
    #[serde(rename_all = "camelCase")]
    For {
        id: String,
        zero: String,
        entered: String,
    },
    /// `l(k, left)` for value-context `&&`/`||`/`||=`/`&&=`.
    #[serde(rename_all = "camelCase")]
    Logical {
        op: String,
        short_circuit: String,
        evaluated: String,
    },
    /// `pre(k)` before an operator assignment whose target cannot be re-read
    /// without side effects, `es(k)` as the first thing its right side does:
    /// arrivals that never started the right side are short-circuits.
    #[serde(rename_all = "camelCase")]
    Arrival {
        short_circuit: String,
        evaluated: String,
    },
    /// `ok(k, v)`/`ok0(k)` completion, `h(k, n)` handler entry, `p(k)`
    /// propagation, `hm(k, v)` rescue-modifier fallback.
    #[serde(rename_all = "camelCase")]
    Try {
        id: String,
        success: String,
        raised: String,
        handlers: Vec<HandlerTarget>,
    },
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, Default)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct RubyFilePlan {
    pub edits: Vec<Edit>,
    /// Line -> statement id for statements that own their first line.
    pub lines: BTreeMap<usize, String>,
    /// Statement id -> [start, end] byte offsets for line-owned statements,
    /// so the runtime can probe one whose first line Ruby turns out not to
    /// count (`begin`, `case` without subject, multi-line literals).
    pub statement_offsets: BTreeMap<String, [usize; 2]>,
    pub branches: Vec<BranchKeyPlan>,
    pub methods: Vec<MethodKeyPlan>,
    pub cases: Vec<CasePlan>,
    /// This file's share of [`RubyProbePlan::probe_obligations`], so a file
    /// the runtime fails to instrument can declare exactly its own.
    #[serde(default)]
    pub probe_obligations: Vec<String>,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct RubyProbePlan {
    pub version: u32,
    pub root: String,
    pub receiver: String,
    pub files: BTreeMap<String, RubyFilePlan>,
    pub probes: BTreeMap<u64, ProbeTarget>,
    /// See [`RubyProbePlan::probe_obligations`]; stored so the runtime can
    /// declare them without re-deriving alternative ids.
    #[serde(default)]
    pub probe_obligations: Vec<String>,
}

impl RubyProbePlan {
    /// Manifest obligations (points, decisions, branches) that only a probe
    /// can prove. An interpreter that cannot apply the insertions reports
    /// them as unmeasured.
    pub fn probe_obligations(&self) -> Vec<String> {
        probe_obligations_of(&self.probes)
    }
}

/// Manifest obligations (points, decisions, branches) that only a probe can
/// prove.
fn probe_obligations_of(probes: &BTreeMap<u64, ProbeTarget>) -> Vec<String> {
    {
        let mut ids = BTreeSet::new();
        for target in probes.values() {
            match target {
                ProbeTarget::Statement { id } => {
                    ids.insert(id.clone());
                }
                ProbeTarget::Decision {
                    id,
                    outcome_true,
                    logical,
                    loop_,
                    ..
                } => {
                    ids.insert(id.clone());
                    ids.insert(branch_of(outcome_true));
                    for derived in logical {
                        ids.insert(branch_of(&derived.short_circuit));
                    }
                    if let Some(loop_) = loop_ {
                        ids.insert(loop_.id.clone());
                    }
                }
                ProbeTarget::For { id, .. } => {
                    ids.insert(id.clone());
                }
                ProbeTarget::Logical { short_circuit, .. } => {
                    ids.insert(branch_of(short_circuit));
                }
                ProbeTarget::Arrival { short_circuit, .. } => {
                    ids.insert(branch_of(short_circuit));
                }
                ProbeTarget::Try { id, handlers, .. } => {
                    ids.insert(id.clone());
                    for handler in handlers {
                        ids.insert(handler.id.clone());
                    }
                }
            }
        }
        ids.into_iter().collect()
    }
}

/// `rb:branch:<hash>:alternative` -> `rb:branch:<hash>`; decision outcome
/// branches are `rb:decision:<hash>:outcome`.
fn branch_of(alternative: &str) -> String {
    alternative
        .rsplit_once(':')
        .map(|(branch, _)| branch.to_owned())
        .unwrap_or_else(|| alternative.to_owned())
}

#[derive(Debug, Clone, PartialEq)]
pub struct RubyFileObligations {
    pub manifest: CoverageManifest,
    pub plan: RubyFilePlan,
    pub probes: BTreeMap<u64, ProbeTarget>,
}

fn stable_id(file: &str, kind: &str, start: usize, end: usize, suffix: &str) -> String {
    let mut hash = Sha256::new();
    for value in [file, kind, &start.to_string(), &end.to_string(), suffix] {
        hash.update(value.as_bytes());
        hash.update([0]);
    }
    let digest = hash.finalize();
    let mut encoded = String::with_capacity(24);
    for byte in &digest[..12] {
        use std::fmt::Write as _;
        write!(&mut encoded, "{byte:02x}").expect("writing to a string cannot fail");
    }
    format!("rb:{kind}:{encoded}")
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
enum EditRank {
    Clause,
    StatementProbe,
    Opener,
    Closer,
}

#[derive(Debug, Clone)]
struct PendingEdit {
    offset: usize,
    rank: EditRank,
    /// Openers sort by ascending depth (outer first), closers by descending.
    order: i64,
    sequence: usize,
    text: String,
    scope: usize,
}

struct Collector<'a> {
    file: &'a str,
    source: &'a [u8],
    line_starts: Vec<usize>,
    manifest: CoverageManifest,
    lines: BTreeMap<usize, String>,
    statement_offsets: BTreeMap<String, [usize; 2]>,
    branches: Vec<BranchKeyPlan>,
    methods: Vec<MethodKeyPlan>,
    cases: Vec<CasePlan>,
    probes: BTreeMap<u64, ProbeTarget>,
    edits: Vec<PendingEdit>,
    next_probe: &'a mut u64,
    point_ids: BTreeSet<String>,
    decision_ids: BTreeSet<String>,
    branch_ids: BTreeSet<String>,
    claimed_lines: BTreeSet<usize>,
    /// Statement start offsets proven by a stdlib branch key (index into
    /// `branches`) instead of a line or a probe.
    key_statements: BTreeMap<usize, usize>,
    /// Start offsets of the body expressions of endless method definitions,
    /// which take a wrapped probe because `def m = s(k); expr` would end the
    /// definition at the probe.
    endless_bodies: std::collections::BTreeSet<usize>,
    /// Offsets of `&&`/`||` nodes that belong to a decision's tree.
    tree_logicals: BTreeSet<usize>,
    /// Statement lists that are expressions in disguise (parentheses, string
    /// interpolation): their children are not statements in the denominator.
    expression_lists: BTreeSet<usize>,
    /// `if`/`unless` nodes that are `case/in` guards, owned by the clause.
    guard_nodes: BTreeSet<usize>,
    /// `elsif` nodes already handled through their parent's chain walk.
    elsif_nodes: BTreeSet<usize>,
    depth: i64,
    begin_unmeasured: Vec<(String, usize)>,
    error: Option<RubyInstrumenterError>,
}

impl<'a> Collector<'a> {
    fn new(file: &'a str, source: &'a [u8], next_probe: &'a mut u64) -> Self {
        let mut line_starts = vec![0];
        line_starts.extend(
            source
                .iter()
                .enumerate()
                .filter_map(|(index, byte)| (*byte == b'\n').then_some(index + 1)),
        );
        Self {
            file,
            source,
            line_starts,
            manifest: CoverageManifest {
                unmeasured: Vec::new(),
                decisions: Vec::new(),
                points: Vec::new(),
                branches: Vec::new(),
                limitations: Vec::new(),
                scope: None,
            },
            lines: BTreeMap::new(),
            statement_offsets: BTreeMap::new(),
            branches: Vec::new(),
            methods: Vec::new(),
            cases: Vec::new(),
            probes: BTreeMap::new(),
            edits: Vec::new(),
            next_probe,
            point_ids: BTreeSet::new(),
            decision_ids: BTreeSet::new(),
            branch_ids: BTreeSet::new(),
            claimed_lines: BTreeSet::new(),
            key_statements: BTreeMap::new(),
            endless_bodies: std::collections::BTreeSet::new(),
            tree_logicals: BTreeSet::new(),
            expression_lists: BTreeSet::new(),
            guard_nodes: BTreeSet::new(),
            elsif_nodes: BTreeSet::new(),
            depth: 0,
            begin_unmeasured: Vec::new(),
            error: None,
        }
    }

    // -- positions ----------------------------------------------------------

    fn line_column(&self, offset: usize) -> (usize, usize) {
        let line_index = self.line_starts.partition_point(|start| *start <= offset) - 1;
        (line_index + 1, offset - self.line_starts[line_index])
    }

    fn span(&self, start: usize, end: usize) -> PlanSpan {
        let (start_line, start_column) = self.line_column(start);
        let (end_line, end_column) = self.line_column(end);
        PlanSpan {
            start: [start_line, start_column],
            end: [end_line, end_column],
        }
    }

    fn point_span(&self, offset: usize) -> PlanSpan {
        let (line, column) = self.line_column(offset);
        PlanSpan {
            start: [line, column],
            end: [line, column],
        }
    }

    fn location_span(&self, location: &Location<'_>) -> PlanSpan {
        self.span(location.start_offset(), location.end_offset())
    }

    fn node_span(&self, node: &Node<'_>) -> PlanSpan {
        self.location_span(&node.location())
    }

    fn text(&self, start: usize, end: usize) -> String {
        String::from_utf8_lossy(&self.source[start.min(end)..end.min(self.source.len())])
            .trim()
            .to_owned()
    }

    fn statements_span(&self, statements: &Option<StatementsNode<'_>>) -> Option<PlanSpan> {
        statements
            .as_ref()
            .map(|statements| self.location_span(&statements.location()))
    }

    // -- edits --------------------------------------------------------------

    fn edit(&mut self, offset: usize, rank: EditRank, text: String, scope: usize) {
        debug_assert!(!text.contains('\n'));
        let order = match rank {
            EditRank::Opener => self.depth,
            EditRank::Closer => -self.depth,
            _ => 0,
        };
        let sequence = self.edits.len();
        self.edits.push(PendingEdit {
            offset,
            rank,
            order,
            sequence,
            text,
            scope,
        });
    }

    fn probe_key(&mut self, target: ProbeTarget) -> u64 {
        let key = *self.next_probe;
        *self.next_probe += 1;
        self.probes.insert(key, target);
        key
    }

    fn wrap(&mut self, start: usize, end: usize, opener: String) {
        self.edit(start, EditRank::Opener, opener, end);
        self.edit(end, EditRank::Closer, "))".into(), start);
    }

    // -- manifest helpers ---------------------------------------------------

    fn push_point(
        &mut self,
        id: &str,
        start: usize,
        end: usize,
        kind: PointKind,
        label: Option<String>,
    ) {
        let (line, column) = self.line_column(start);
        self.manifest.points.push(PointMeta {
            id: id.into(),
            kind,
            file: self.file.into(),
            line,
            column,
            source: self.text(start, end),
            label,
        });
    }

    fn branch<const N: usize>(
        &mut self,
        start: usize,
        end: usize,
        kind: &str,
        alternatives: [(&str, &str); N],
    ) -> Option<String> {
        let id = stable_id(self.file, "branch", start, end, kind);
        let source = self.text(start, end);
        self.branch_with_id(id, start, end, kind, source, alternatives)
    }

    fn branch_with_id<const N: usize>(
        &mut self,
        id: String,
        start: usize,
        _end: usize,
        kind: &str,
        source: String,
        alternatives: [(&str, &str); N],
    ) -> Option<String> {
        if !self.branch_ids.insert(id.clone()) {
            return None;
        }
        let (line, column) = self.line_column(start);
        self.manifest.branches.push(BranchMeta {
            id: id.clone(),
            kind: kind.into(),
            file: self.file.into(),
            line,
            column,
            source,
            alternatives: alternatives
                .into_iter()
                .map(|(suffix, label)| BranchAlternativeMeta {
                    id: format!("{id}:{suffix}"),
                    label: label.into(),
                })
                .collect(),
        });
        Some(id)
    }

    fn stdlib(
        &mut self,
        group: &str,
        branch: &str,
        span: PlanSpan,
        kind: KeyKind,
        hits: Vec<String>,
    ) -> usize {
        self.branches.push(BranchKeyPlan {
            key: StdlibKey {
                group: group.into(),
                branch: branch.into(),
                kind,
                span,
                unshifted: span,
            },
            hits,
            decision: None,
        });
        self.branches.len() - 1
    }

    // -- statements ---------------------------------------------------------

    fn statements(&mut self, statements: &StatementsNode<'_>) {
        for statement in statements.body().iter() {
            self.statement(&statement);
        }
    }

    fn statement(&mut self, node: &Node<'_>) {
        let location = node.location();
        let (start, end) = (location.start_offset(), location.end_offset());
        let id = stable_id(self.file, "statement", start, end, "");
        if !self.point_ids.insert(id.clone()) {
            return;
        }
        self.push_point(&id, start, end, PointKind::Statement, None);
        let (line, _) = self.line_column(start);
        if let Some(index) = self.key_statements.get(&start).copied() {
            // The body of a modifier or one-line branch: the stdlib branch
            // key that proves the branch proves this statement.
            self.branches[index].hits.push(id);
        } else if self.needs_probe(node) {
            // No instruction carries this statement's first line: `x = begin`
            // starts executing inside the begin body.
            self.claimed_lines.insert(line);
            let key = self.probe_key(ProbeTarget::Statement { id });
            self.statement_probe(start, end, key);
        } else if self.claimed_lines.insert(line) {
            // Ruby's line table counts the statement's first line; the
            // offsets let the runtime probe it instead where the interpreter
            // turns out not to count that line.
            self.lines.insert(line, id.clone());
            self.statement_offsets.insert(id, [start, end]);
        } else {
            let key = self.probe_key(ProbeTarget::Statement { id });
            self.statement_probe(start, end, key);
        }
    }

    /// `s(k); statement`, or `(s(k); expression)` for the body of an endless
    /// method definition, which admits exactly one expression.
    fn statement_probe(&mut self, start: usize, end: usize, key: u64) {
        if self.endless_bodies.contains(&start) {
            self.depth += 1;
            self.edit(
                start,
                EditRank::Opener,
                format!("({RUBY_PROBE_RECEIVER}.s({key}); "),
                end,
            );
            self.edit(end, EditRank::Closer, ")".into(), start);
            self.depth -= 1;
        } else {
            self.edit(
                start,
                EditRank::StatementProbe,
                format!("{RUBY_PROBE_RECEIVER}.s({key}); "),
                end,
            );
        }
    }

    fn needs_probe(&self, node: &Node<'_>) -> bool {
        let value = if let Some(write) = node.as_local_variable_write_node() {
            Some(write.value())
        } else if let Some(write) = node.as_instance_variable_write_node() {
            Some(write.value())
        } else if let Some(write) = node.as_class_variable_write_node() {
            Some(write.value())
        } else if let Some(write) = node.as_global_variable_write_node() {
            Some(write.value())
        } else if let Some(write) = node.as_constant_write_node() {
            Some(write.value())
        } else {
            node.as_multi_write_node().map(|write| write.value())
        };
        // `x = begin ... end` and `x = (\n ... )` start executing inside the
        // value on a later line; Ruby records nothing for the assignment line.
        value.is_some_and(|value| {
            value
                .as_begin_node()
                .is_some_and(|begin| begin.begin_keyword_loc().is_some())
                || value.as_parentheses_node().is_some()
        })
    }

    /// Register the first statement of a body as proven by a stdlib key.
    fn key_body(&mut self, statements: Option<StatementsNode<'_>>, index: usize) {
        if let Some(first) = statements.and_then(|statements| statements.body().iter().next()) {
            self.key_statements
                .insert(first.location().start_offset(), index);
        }
    }

    // -- decisions ----------------------------------------------------------

    /// Strip parentheses and `!`/`not`, counting the negations.
    fn strip<'n>(&self, node: Node<'n>) -> (Node<'n>, usize) {
        let mut current = node;
        let mut not = 0;
        loop {
            if let Some(parens) = current.as_parentheses_node() {
                if !parens.is_multiple_statements()
                    && let Some(body) = parens.body()
                    && let Some(statements) = body.as_statements_node()
                    && statements.body().iter().count() == 1
                    && let Some(inner) = statements.body().iter().next()
                {
                    current = inner;
                    continue;
                }
                break;
            }
            if let Some(call) = current.as_call_node()
                && call.name().as_slice() == b"!"
                && call.arguments().is_none()
                && call.block().is_none()
                && let Some(receiver) = call.receiver()
            {
                not += 1;
                current = receiver;
                continue;
            }
            break;
        }
        (current, not)
    }

    fn tree(
        &mut self,
        node: Node<'_>,
        leaves: &mut Vec<(usize, usize, usize)>,
        logicals: &mut Vec<(String, Vec<Vec<usize>>)>,
    ) -> ConditionTree {
        let (operand, not) = self.strip(node);
        let logical: Option<(&str, Node<'_>, Node<'_>, usize)> =
            if let Some(and) = operand.as_and_node() {
                Some((
                    "and",
                    and.left(),
                    and.right(),
                    operand.location().start_offset(),
                ))
            } else if let Some(or) = operand.as_or_node() {
                Some((
                    "or",
                    or.left(),
                    or.right(),
                    operand.location().start_offset(),
                ))
            } else {
                None
            };
        if let Some((op, left, right, offset)) = logical {
            self.tree_logicals.insert(offset);
            let first = leaves.len();
            let left_tree = self.tree(left, leaves, logicals);
            let middle = leaves.len();
            let right_tree = self.tree(right, leaves, logicals);
            logicals.push((
                op.into(),
                vec![(first..middle).collect(), (middle..leaves.len()).collect()],
            ));
            return ConditionTree::Node {
                op: op.into(),
                items: vec![left_tree, right_tree],
                negate: not % 2 == 1,
            };
        }
        let location = operand.location();
        leaves.push((location.start_offset(), location.end_offset(), not));
        ConditionTree::Leaf(leaves.len() - 1)
    }

    /// A decision proven by probes: multi-condition predicates, loop
    /// predicates and pattern guards. Returns the probe key the outcome
    /// wrapper must use.
    fn probe_decision(
        &mut self,
        predicate: Node<'_>,
        kind: &str,
        loop_: Option<LoopTarget>,
        wrapper: &str,
    ) -> Option<u64> {
        let location = predicate.location();
        let (start, end) = (location.start_offset(), location.end_offset());
        let id = stable_id(self.file, "decision", start, end, kind);
        if !self.decision_ids.insert(id.clone()) {
            return None;
        }
        let mut leaves = Vec::new();
        let mut logicals = Vec::new();
        let tree = self.tree(predicate, &mut leaves, &mut logicals);
        let conditions = leaves
            .iter()
            .map(|(leaf_start, leaf_end, not)| {
                let text = self.text(*leaf_start, *leaf_end);
                if not % 2 == 1 {
                    format!("!{text}")
                } else {
                    text
                }
            })
            .collect::<Vec<_>>();
        let (line, column) = self.line_column(start);
        let source = self.text(start, end);
        self.manifest.decisions.push(DecisionMeta {
            id: id.clone(),
            file: self.file.into(),
            line,
            column,
            source: source.clone(),
            conditions,
            kind: kind.into(),
        });
        let outcome_id = format!("{id}:outcome");
        self.branch_with_id(
            outcome_id.clone(),
            start,
            end,
            kind,
            source,
            [("true", "true"), ("false", "false")],
        );
        let mut derived = Vec::new();
        for (op, groups) in logicals {
            // The logical branch lives on the right operand's range.
            let right_leaf = groups[1].first().copied().unwrap_or(0);
            let (right_start, right_end, _) = leaves[right_leaf];
            if let Some(branch_id) = self.branch(
                right_start,
                right_end,
                &format!("logical-{op}"),
                [
                    ("short-circuit", "short-circuited"),
                    ("evaluated", "right operand evaluated"),
                ],
            ) {
                derived.push(DerivedLogical {
                    previous_leaves: groups[0].clone(),
                    operand_leaves: groups[1].clone(),
                    short_circuit: format!("{branch_id}:short-circuit"),
                    evaluated: format!("{branch_id}:evaluated"),
                });
            }
        }
        let key = self.probe_key(ProbeTarget::Decision {
            id,
            width: leaves.len(),
            not: leaves.iter().map(|(_, _, not)| not % 2 == 1).collect(),
            tree,
            outcome_true: format!("{outcome_id}:true"),
            outcome_false: format!("{outcome_id}:false"),
            logical: derived,
            loop_,
        });
        self.depth += 1;
        self.wrap(
            start,
            end,
            format!("{RUBY_PROBE_RECEIVER}.{wrapper}({key}, ("),
        );
        self.depth += 1;
        for (index, (leaf_start, leaf_end, _)) in leaves.iter().enumerate() {
            self.wrap(
                *leaf_start,
                *leaf_end,
                format!("{RUBY_PROBE_RECEIVER}.c({key}, {index}, ("),
            );
        }
        self.depth -= 2;
        Some(key)
    }

    /// A single-condition `if`/`unless`/ternary decision: Ruby's `then`/`else`
    /// counts already witness both outcomes, so no probe is inserted.
    fn stdlib_decision(
        &mut self,
        predicate: Node<'_>,
        kind: &str,
        then_index: usize,
        else_index: usize,
        then_is_true: bool,
    ) {
        let location = predicate.location();
        let (start, end) = (location.start_offset(), location.end_offset());
        let id = stable_id(self.file, "decision", start, end, kind);
        if !self.decision_ids.insert(id.clone()) {
            return;
        }
        let (operand, not) = self.strip(predicate);
        let operand_location = operand.location();
        let mut condition = self.text(
            operand_location.start_offset(),
            operand_location.end_offset(),
        );
        if not % 2 == 1 {
            condition = format!("!{condition}");
        }
        let (line, column) = self.line_column(start);
        let source = self.text(start, end);
        self.manifest.decisions.push(DecisionMeta {
            id: id.clone(),
            file: self.file.into(),
            line,
            column,
            source: source.clone(),
            conditions: vec![condition],
            kind: kind.into(),
        });
        let outcome_id = format!("{id}:outcome");
        self.branch_with_id(
            outcome_id.clone(),
            start,
            end,
            kind,
            source,
            [("true", "true"), ("false", "false")],
        );
        let (true_index, false_index) = if then_is_true {
            (then_index, else_index)
        } else {
            (else_index, then_index)
        };
        self.branches[true_index].decision = Some(StdlibDecision {
            id: id.clone(),
            value: true,
            outcome: format!("{outcome_id}:true"),
        });
        self.branches[false_index].decision = Some(StdlibDecision {
            id,
            value: false,
            outcome: format!("{outcome_id}:false"),
        });
    }

    /// `Some(truthiness)` for a predicate Ruby folds at compile time: a
    /// `true`, `false` or `nil` literal, or a numeric, string or symbol
    /// literal, possibly parenthesised. Ruby emits neither a branch nor the
    /// dead arm for these.
    fn literal_truth(&self, predicate: Node<'_>) -> Option<bool> {
        let mut node = predicate;
        loop {
            let inner = node.as_parentheses_node().and_then(|parens| {
                let body = parens.body()?;
                let statements = body.as_statements_node()?;
                let mut iter = statements.body().iter();
                let only = iter.next()?;
                iter.next().is_none().then_some(only)
            });
            match inner {
                Some(inner) => node = inner,
                None => break,
            }
        }
        if node.as_true_node().is_some()
            || node.as_integer_node().is_some()
            || node.as_float_node().is_some()
            || node.as_rational_node().is_some()
            || node.as_imaginary_node().is_some()
            || node.as_string_node().is_some()
            || node.as_symbol_node().is_some()
        {
            Some(true)
        } else if node.as_false_node().is_some() || node.as_nil_node().is_some() {
            Some(false)
        } else {
            None
        }
    }

    fn is_compound(&self, predicate: Node<'_>) -> bool {
        let (operand, _) = self.strip(predicate);
        operand.as_and_node().is_some() || operand.as_or_node().is_some()
    }

    /// `predicate` is called twice because Prism nodes are handles that
    /// cannot be copied; every call returns the same node.
    fn predicate_decision<'n>(
        &mut self,
        predicate: impl Fn() -> Node<'n>,
        kind: &str,
        then_index: usize,
        else_index: usize,
        then_is_true: bool,
    ) {
        if self.is_compound(predicate()) {
            self.probe_decision(predicate(), kind, None, "d");
        } else {
            self.stdlib_decision(predicate(), kind, then_index, else_index, then_is_true);
        }
    }

    // -- constructs ---------------------------------------------------------

    fn if_node(&mut self, node: &IfNode<'_>, kind: &str) {
        let location = node.location();
        let node_span = self.location_span(&location);
        let then_statements = self.statements_span(&node.statements());
        // An `if` without a body gets a zero-width key at its predicate's end.
        let (then_span, then_kind) = match then_statements {
            Some(span) => (span, KeyKind::List),
            None => (
                self.point_span(node.predicate().location().end_offset()),
                KeyKind::Point,
            ),
        };
        let (else_span, else_kind) = match node.subsequent() {
            Some(subsequent) => match subsequent.as_else_node() {
                Some(else_node) => match self.statements_span(&else_node.statements()) {
                    Some(span) => (span, KeyKind::List),
                    None => (self.node_span(&subsequent), KeyKind::Node),
                },
                None => (self.node_span(&subsequent), KeyKind::Node),
            },
            None => (node_span, KeyKind::Node),
        };
        let then_index = self.stdlib("if", "then", then_span, then_kind, Vec::new());
        let else_index = self.stdlib("if", "else", else_span, else_kind, Vec::new());
        if kind == "ternary" {
            // A ternary's arms are expressions, not statements.
            if let Some(statements) = node.statements() {
                self.expression_lists
                    .insert(statements.location().start_offset());
            }
            if let Some(subsequent) = node.subsequent()
                && let Some(else_node) = subsequent.as_else_node()
                && let Some(statements) = else_node.statements()
            {
                self.expression_lists
                    .insert(statements.location().start_offset());
            }
        } else {
            self.key_body(node.statements(), then_index);
            if let Some(subsequent) = node.subsequent()
                && let Some(else_node) = subsequent.as_else_node()
            {
                self.key_body(else_node.statements(), else_index);
            }
        }
        self.predicate_decision(|| node.predicate(), kind, then_index, else_index, true);
    }

    fn unless_node(&mut self, node: &UnlessNode<'_>) {
        let node_span = self.location_span(&node.location());
        let then_statements = self.statements_span(&node.statements());
        let (then_span, then_kind) = match then_statements {
            Some(span) => (span, KeyKind::List),
            None => (
                self.point_span(node.predicate().location().end_offset()),
                KeyKind::Point,
            ),
        };
        let (else_span, else_kind) = match node.else_clause() {
            Some(else_node) => match self.statements_span(&else_node.statements()) {
                Some(span) => (span, KeyKind::List),
                None => (self.location_span(&else_node.location()), KeyKind::Node),
            },
            None => (node_span, KeyKind::Node),
        };
        let then_index = self.stdlib("unless", "then", then_span, then_kind, Vec::new());
        let else_index = self.stdlib("unless", "else", else_span, else_kind, Vec::new());
        self.key_body(node.statements(), then_index);
        if let Some(else_node) = node.else_clause() {
            self.key_body(else_node.statements(), else_index);
        }
        // `unless` runs `then` when the predicate is falsy.
        self.predicate_decision(|| node.predicate(), "unless", then_index, else_index, false);
    }

    fn loop_node(
        &mut self,
        location: &Location<'_>,
        predicate: Node<'_>,
        statements: Option<StatementsNode<'_>>,
        begin_modifier: bool,
        until: bool,
    ) {
        let kind = if until { "until" } else { "while" };
        let (start, end) = (location.start_offset(), location.end_offset());
        // The stdlib `body` key proves a same-offset modifier body statement.
        if let Some(body_span) = self.statements_span(&statements) {
            let index = self.stdlib(kind, "body", body_span, KeyKind::List, Vec::new());
            self.key_body(statements, index);
        }
        let loop_target = if begin_modifier {
            // `begin ... end while` always enters the body once.
            None
        } else {
            self.branch(
                start,
                end,
                kind,
                [("zero", "zero iterations"), ("entered", "entered")],
            )
            .map(|id| LoopTarget {
                zero: format!("{id}:zero"),
                entered: format!("{id}:entered"),
                id,
                until,
            })
        };
        self.probe_decision(predicate, kind, loop_target, "w");
    }

    fn for_node(&mut self, node: &ForNode<'_>) {
        let location = node.location();
        let Some(id) = self.branch(
            location.start_offset(),
            location.end_offset(),
            "for",
            [("zero", "zero iterations"), ("entered", "entered")],
        ) else {
            return;
        };
        let key = self.probe_key(ProbeTarget::For {
            zero: format!("{id}:zero"),
            entered: format!("{id}:entered"),
            id: id.clone(),
        });
        let collection = node.collection().location();
        self.depth += 1;
        self.wrap(
            collection.start_offset(),
            collection.end_offset(),
            format!("{RUBY_PROBE_RECEIVER}.f({key}, ("),
        );
        self.depth -= 1;
        match node
            .statements()
            .and_then(|statements| statements.body().iter().next())
        {
            Some(first) => self.edit(
                first.location().start_offset(),
                EditRank::StatementProbe,
                format!("{RUBY_PROBE_RECEIVER}.fb({key}); "),
                first.location().end_offset(),
            ),
            None => {
                self.manifest.unmeasured.push(format!("{id}:entered"));
                self.manifest.unmeasured.push(format!("{id}:zero"));
            }
        }
    }

    /// `items.each { ... }` and friends: Ruby's loops are usually method
    /// calls with a block. The receiver is wrapped like a `for` collection
    /// and the block body gets the entry probe, so zero-versus-entered is
    /// exact for every iterator in [`ITERATORS`].
    fn iterator_loop(
        &mut self,
        node: &CallNode<'_>,
        receiver: &Node<'_>,
        block: &ruby_prism::BlockNode<'_>,
    ) {
        let location = node.location();
        let name = String::from_utf8_lossy(node.name().as_slice()).into_owned();
        let Some(id) = self.branch(
            location.start_offset(),
            location.end_offset(),
            &format!("iterator-{}", name.trim_end_matches(['?', '!'])),
            [("zero", "zero iterations"), ("entered", "entered")],
        ) else {
            return;
        };
        let first = block.body().and_then(|body| {
            if let Some(statements) = body.as_statements_node() {
                statements.body().iter().next()
            } else if let Some(begin) = body.as_begin_node() {
                begin
                    .statements()
                    .and_then(|statements| statements.body().iter().next())
            } else {
                None
            }
        });
        let Some(first) = first else {
            // An empty block never enters; both alternatives stay declared
            // but nothing can witness them.
            self.manifest.unmeasured.push(format!("{id}:entered"));
            self.manifest.unmeasured.push(format!("{id}:zero"));
            return;
        };
        let key = self.probe_key(ProbeTarget::For {
            zero: format!("{id}:zero"),
            entered: format!("{id}:entered"),
            id,
        });
        let receiver_location = receiver.location();
        self.depth += 1;
        self.wrap(
            receiver_location.start_offset(),
            receiver_location.end_offset(),
            format!("{RUBY_PROBE_RECEIVER}.f({key}, ("),
        );
        self.depth -= 1;
        self.edit(
            first.location().start_offset(),
            EditRank::StatementProbe,
            format!("{RUBY_PROBE_RECEIVER}.fb({key}); "),
            first.location().end_offset(),
        );
    }

    fn case_node(&mut self, node: &CaseNode<'_>) {
        let node_span = self.location_span(&node.location());
        let (start, end) = (node.location().start_offset(), node.location().end_offset());
        let mut clauses = Vec::new();
        for (index, condition) in node.conditions().iter().enumerate() {
            let Some(when) = condition.as_when_node() else {
                continue;
            };
            let Some(id) = self.branch(
                when.location().start_offset(),
                when.location().end_offset(),
                &format!("case-when-{index}"),
                [("missed", "not selected"), ("selected", "selected")],
            ) else {
                return;
            };
            let statements = self.statements_span(&when.statements());
            let span = statements.unwrap_or_else(|| self.location_span(&when.location()));
            let key_index = self.stdlib(
                "case",
                "when",
                span,
                if statements.is_some() {
                    KeyKind::List
                } else {
                    KeyKind::Node
                },
                vec![format!("{id}:selected")],
            );
            self.key_body(when.statements(), key_index);
            clauses.push(CaseClausePlan {
                key: self.branches[key_index].key.clone(),
                missed: format!("{id}:missed"),
                selected: format!("{id}:selected"),
            });
        }
        let no_match = match node.else_clause() {
            Some(else_node) => {
                let Some(id) = self.branch(
                    else_node.location().start_offset(),
                    else_node.location().end_offset(),
                    "case-else",
                    [("missed", "not selected"), ("selected", "selected")],
                ) else {
                    return;
                };
                let statements = self.statements_span(&else_node.statements());
                let span = statements.unwrap_or_else(|| self.location_span(&else_node.location()));
                let key_index = self.stdlib(
                    "case",
                    "else",
                    span,
                    if statements.is_some() {
                        KeyKind::List
                    } else {
                        KeyKind::Node
                    },
                    vec![format!("{id}:selected")],
                );
                self.key_body(else_node.statements(), key_index);
                clauses.push(CaseClausePlan {
                    key: self.branches[key_index].key.clone(),
                    missed: format!("{id}:missed"),
                    selected: format!("{id}:selected"),
                });
                None
            }
            None => self
                .branch(
                    start,
                    end,
                    "case-no-match",
                    [
                        ("matched", "some clause matched"),
                        ("unmatched", "no clause matched"),
                    ],
                )
                .map(|id| {
                    let key_index = self.stdlib(
                        "case",
                        "else",
                        node_span,
                        KeyKind::Node,
                        vec![format!("{id}:unmatched")],
                    );
                    CaseNoMatchPlan {
                        key: self.branches[key_index].key.clone(),
                        matched: format!("{id}:matched"),
                        unmatched: format!("{id}:unmatched"),
                    }
                }),
        };
        self.cases.push(CasePlan { clauses, no_match });
    }

    fn case_match_node(&mut self, node: &CaseMatchNode<'_>) {
        let node_span = self.location_span(&node.location());
        let (start, end) = (node.location().start_offset(), node.location().end_offset());
        let mut clauses = Vec::new();
        for (index, condition) in node.conditions().iter().enumerate() {
            let Some(in_node) = condition.as_in_node() else {
                continue;
            };
            let Some(id) = self.branch(
                in_node.location().start_offset(),
                in_node.location().end_offset(),
                &format!("case-in-{index}"),
                [("missed", "not selected"), ("selected", "selected")],
            ) else {
                return;
            };
            let statements = self.statements_span(&in_node.statements());
            let span = statements.unwrap_or_else(|| self.location_span(&in_node.location()));
            let key_index = self.stdlib(
                "case",
                "in",
                span,
                if statements.is_some() {
                    KeyKind::List
                } else {
                    KeyKind::Node
                },
                vec![format!("{id}:selected")],
            );
            self.key_body(in_node.statements(), key_index);
            clauses.push(CaseClausePlan {
                key: self.branches[key_index].key.clone(),
                missed: format!("{id}:missed"),
                selected: format!("{id}:selected"),
            });
            // A guard is a decision of its own; Ruby reports no branch key
            // for it, so it is always probe-driven.
            let pattern = in_node.pattern();
            if let Some(guard) = pattern.as_if_node() {
                self.guard_nodes.insert(pattern.location().start_offset());
                self.probe_decision(guard.predicate(), "in-guard", None, "d");
            } else if let Some(guard) = pattern.as_unless_node() {
                self.guard_nodes.insert(pattern.location().start_offset());
                self.probe_decision(guard.predicate(), "in-guard-unless", None, "d");
            }
        }
        let no_match = match node.else_clause() {
            Some(else_node) => {
                let Some(id) = self.branch(
                    else_node.location().start_offset(),
                    else_node.location().end_offset(),
                    "case-else",
                    [("missed", "not selected"), ("selected", "selected")],
                ) else {
                    return;
                };
                let statements = self.statements_span(&else_node.statements());
                let span = statements.unwrap_or_else(|| self.location_span(&else_node.location()));
                let key_index = self.stdlib(
                    "case",
                    "else",
                    span,
                    if statements.is_some() {
                        KeyKind::List
                    } else {
                        KeyKind::Node
                    },
                    vec![format!("{id}:selected")],
                );
                self.key_body(else_node.statements(), key_index);
                clauses.push(CaseClausePlan {
                    key: self.branches[key_index].key.clone(),
                    missed: format!("{id}:missed"),
                    selected: format!("{id}:selected"),
                });
                None
            }
            None => self
                .branch(
                    start,
                    end,
                    "case-no-match",
                    [
                        ("matched", "some pattern matched"),
                        ("unmatched", "no pattern matched"),
                    ],
                )
                .map(|id| {
                    let key_index = self.stdlib(
                        "case",
                        "else",
                        node_span,
                        KeyKind::Node,
                        vec![format!("{id}:unmatched")],
                    );
                    CaseNoMatchPlan {
                        key: self.branches[key_index].key.clone(),
                        matched: format!("{id}:matched"),
                        unmatched: format!("{id}:unmatched"),
                    }
                }),
        };
        self.cases.push(CasePlan { clauses, no_match });
    }

    fn safe_navigation(&mut self, node: &CallNode<'_>) {
        let location = node.location();
        let Some(id) = self.branch(
            location.start_offset(),
            location.end_offset(),
            "safe-navigation",
            [("nil", "receiver nil"), ("called", "method called")],
        ) else {
            return;
        };
        // Ruby's key runs from the receiver to the closing parenthesis or the
        // last argument, and to the message when there are no arguments; a
        // block or block argument is never part of it.
        let end = match node.arguments() {
            Some(arguments) => node
                .closing_loc()
                .map(|closing| closing.end_offset())
                .unwrap_or_else(|| arguments.location().end_offset()),
            None => node
                .message_loc()
                .map(|message| message.end_offset())
                .unwrap_or_else(|| location.end_offset()),
        };
        let (start_line, start_column) = self.line_column(location.start_offset());
        let (end_line, end_column) = self.line_column(end);
        let span = PlanSpan {
            start: [start_line, start_column],
            end: [end_line, end_column],
        };
        self.stdlib(
            "&.",
            "then",
            span,
            KeyKind::Node,
            vec![format!("{id}:called")],
        );
        self.stdlib("&.", "else", span, KeyKind::Node, vec![format!("{id}:nil")]);
    }

    fn value_logical(&mut self, op: &str, left: &Node<'_>, node_start: usize, node_end: usize) {
        let Some(id) = self.branch(
            node_start,
            node_end,
            &format!("logical-{op}"),
            [
                ("short-circuit", "short-circuited"),
                ("evaluated", "right operand evaluated"),
            ],
        ) else {
            return;
        };
        let key = self.probe_key(ProbeTarget::Logical {
            op: op.into(),
            short_circuit: format!("{id}:short-circuit"),
            evaluated: format!("{id}:evaluated"),
        });
        let left = left.location();
        self.depth += 1;
        self.wrap(
            left.start_offset(),
            left.end_offset(),
            format!("{RUBY_PROBE_RECEIVER}.l({key}, ("),
        );
        self.depth -= 1;
    }

    /// `x ||= v` / `x &&= v`. A variable target can be re-read without side
    /// effects, so the whole expression becomes `(l(k, x); x ||= v)`; other
    /// targets only get the evaluated side.
    fn op_assign(
        &mut self,
        op: &str,
        node_start: usize,
        node_end: usize,
        name: Option<&[u8]>,
        value: &Node<'_>,
    ) {
        let Some(id) = self.branch(
            node_start,
            node_end,
            &format!("{op}-assign"),
            [
                ("short-circuit", "assignment skipped"),
                ("evaluated", "value evaluated and assigned"),
            ],
        ) else {
            return;
        };
        match name {
            Some(name) => {
                let key = self.probe_key(ProbeTarget::Logical {
                    op: op.into(),
                    short_circuit: format!("{id}:short-circuit"),
                    evaluated: format!("{id}:evaluated"),
                });
                let name = String::from_utf8_lossy(name);
                self.depth += 1;
                self.edit(
                    node_start,
                    EditRank::Opener,
                    format!("({RUBY_PROBE_RECEIVER}.l({key}, {name}); "),
                    node_end,
                );
                self.edit(node_end, EditRank::Closer, ")".into(), node_start);
                self.depth -= 1;
            }
            None => {
                // `(pre(k); recv[i] ||= (es(k); v))`: the target is evaluated
                // exactly once, as before; arrivals and right-side starts are
                // counted per phase and their difference is the skipped side.
                let key = self.probe_key(ProbeTarget::Arrival {
                    short_circuit: format!("{id}:short-circuit"),
                    evaluated: format!("{id}:evaluated"),
                });
                let value_location = value.location();
                self.depth += 1;
                self.edit(
                    node_start,
                    EditRank::Opener,
                    format!("({RUBY_PROBE_RECEIVER}.pre({key}); "),
                    node_end,
                );
                self.edit(node_end, EditRank::Closer, ")".into(), node_start);
                self.depth += 1;
                self.edit(
                    value_location.start_offset(),
                    EditRank::Opener,
                    format!("({RUBY_PROBE_RECEIVER}.es({key}); "),
                    value_location.end_offset(),
                );
                self.edit(
                    value_location.end_offset(),
                    EditRank::Closer,
                    ")".into(),
                    value_location.start_offset(),
                );
                self.depth -= 2;
            }
        }
    }

    // -- exception flow -----------------------------------------------------

    /// `begin`/`rescue`/`else`/`ensure` in any host: explicit `begin`, a
    /// method body, or a `do` block. `close` is where the closing keyword
    /// lives, which is where the propagation clause is inserted when the
    /// construct has no `else` or `ensure`.
    fn begin_node(&mut self, node: &BeginNode<'_>, close: Option<usize>) {
        let has_rescue = node.rescue_clause().is_some();
        let has_ensure = node.ensure_clause().is_some();
        if !has_rescue && !has_ensure {
            return;
        }
        let location = node.location();
        let (start, end) = (location.start_offset(), location.end_offset());
        let Some(id) = self.branch(
            start,
            end,
            "begin",
            [
                ("success", "body completed"),
                ("raised", "exception raised"),
            ],
        ) else {
            return;
        };
        let mut handlers = Vec::new();
        let mut handler_edits = Vec::new();
        let mut rescue = node.rescue_clause();
        let mut index = 0;
        while let Some(clause) = rescue {
            let clause_location = clause.location();
            let Some(handler_id) = self.branch(
                clause_location.start_offset(),
                clause_location.end_offset(),
                &format!("rescue-{index}"),
                [("missed", "not selected"), ("selected", "selected")],
            ) else {
                return;
            };
            handlers.push(HandlerTarget {
                missed: format!("{handler_id}:missed"),
                selected: format!("{handler_id}:selected"),
                id: handler_id,
            });
            handler_edits.push(self.handler_probe_position(&clause));
            rescue = clause.subsequent();
            index += 1;
        }
        let key = self.probe_key(ProbeTarget::Try {
            success: format!("{id}:success"),
            raised: format!("{id}:raised"),
            id: id.clone(),
            handlers,
        });
        for (index, (offset, leading, scope_end)) in handler_edits.into_iter().enumerate() {
            let text = if leading {
                format!("; {RUBY_PROBE_RECEIVER}.h({key}, {index})")
            } else {
                format!("{RUBY_PROBE_RECEIVER}.h({key}, {index}); ")
            };
            self.edit(offset, EditRank::StatementProbe, text, scope_end);
        }
        // Propagation clause: after every user clause, before else/ensure/end.
        let clause_offset = node
            .else_clause()
            .map(|clause| clause.else_keyword_loc().start_offset())
            .or_else(|| {
                node.ensure_clause()
                    .map(|clause| clause.ensure_keyword_loc().start_offset())
            })
            .or_else(|| node.end_keyword_loc().map(|loc| loc.start_offset()))
            .or(close);
        match clause_offset {
            Some(offset) => self.edit(
                offset,
                EditRank::Clause,
                format!(
                    "rescue Exception => __supercov_e; {RUBY_PROBE_RECEIVER}.p({key}); raise; "
                ),
                offset,
            ),
            None => {
                self.manifest.unmeasured.push(format!("{id}:raised"));
                let (line, _) = self.line_column(start);
                self.begin_unmeasured.push((id.clone(), line));
            }
        }
        // Completion: the else clause runs only after a completed body.
        if let Some(else_clause) = node.else_clause() {
            match else_clause
                .statements()
                .and_then(|statements| statements.body().iter().next())
            {
                Some(first) => self.edit(
                    first.location().start_offset(),
                    EditRank::StatementProbe,
                    format!("{RUBY_PROBE_RECEIVER}.ok0({key}); "),
                    first.location().end_offset(),
                ),
                None => self.edit(
                    else_clause.else_keyword_loc().end_offset(),
                    EditRank::StatementProbe,
                    format!(" {RUBY_PROBE_RECEIVER}.ok0({key});"),
                    else_clause.else_keyword_loc().end_offset(),
                ),
            }
            return;
        }
        let last = node
            .statements()
            .and_then(|statements| statements.body().iter().last());
        match last {
            Some(last) => {
                if !self.completion_probe(last, key) {
                    self.manifest.unmeasured.push(format!("{id}:success"));
                    let (line, _) = self.line_column(start);
                    self.begin_unmeasured.push((id, line));
                }
            }
            None => {
                self.manifest.unmeasured.push(format!("{id}:success"));
                let (line, _) = self.line_column(start);
                self.begin_unmeasured.push((id, line));
            }
        }
    }

    /// Where the handler-entry probe goes: before the first body statement,
    /// or right after the clause header when the body is empty.
    fn handler_probe_position(&self, clause: &RescueNode<'_>) -> (usize, bool, usize) {
        if let Some(first) = clause
            .statements()
            .and_then(|statements| statements.body().iter().next())
        {
            return (
                first.location().start_offset(),
                false,
                first.location().end_offset(),
            );
        }
        let offset = if let Some(then_keyword) = clause.then_keyword_loc() {
            then_keyword.end_offset()
        } else if let Some(reference) = clause.reference() {
            reference.location().end_offset()
        } else if let Some(last) = clause.exceptions().iter().last() {
            last.location().end_offset()
        } else {
            clause.keyword_loc().end_offset()
        };
        (offset, true, offset)
    }

    /// True for an expression whose own value can be a jump: a `return`,
    /// `break`, `next`, `redo` or `retry`, or an `if`, `unless`, ternary,
    /// `case` or nested `begin` with an arm that ends in one. Such an
    /// expression may not be wrapped. Ruby rejects the parenthesised form
    /// outright when every arm is a jump ("void value expression"), and when
    /// only some arms are, passing it as an argument -- which is what a
    /// wrapper does -- makes the compiler miscount its stack ("argument stack
    /// underflow") for shapes that are hard to predict. Its arms are probed
    /// instead. A jump reached through a block, a loop or `&&`/`||` belongs to
    /// that construct rather than to this expression's value, and is fine.
    fn jump_exposed(&self, node: &Node<'_>) -> bool {
        if Self::is_jump(node) {
            return true;
        }
        if let Some(if_node) = node.as_if_node() {
            let else_exposed = match if_node.subsequent() {
                Some(subsequent) => match subsequent.as_else_node() {
                    Some(else_node) => self.arm_jump_exposed(else_node.statements()),
                    None => self.jump_exposed(&subsequent),
                },
                None => false,
            };
            return else_exposed || self.arm_jump_exposed(if_node.statements());
        }
        if let Some(unless_node) = node.as_unless_node() {
            let else_exposed = match unless_node.else_clause() {
                Some(else_node) => self.arm_jump_exposed(else_node.statements()),
                None => false,
            };
            return else_exposed || self.arm_jump_exposed(unless_node.statements());
        }
        if let Some(begin) = node.as_begin_node() {
            if self.arm_jump_exposed(begin.statements())
                || begin
                    .else_clause()
                    .is_some_and(|else_node| self.arm_jump_exposed(else_node.statements()))
            {
                return true;
            }
            let mut rescue = begin.rescue_clause();
            while let Some(clause) = rescue {
                if self.arm_jump_exposed(clause.statements()) {
                    return true;
                }
                rescue = clause.subsequent();
            }
            return false;
        }
        if let Some(case_node) = node.as_case_node() {
            return case_node
                .conditions()
                .iter()
                .any(|condition| match condition.as_when_node() {
                    Some(when_node) => self.arm_jump_exposed(when_node.statements()),
                    None => false,
                })
                || case_node
                    .else_clause()
                    .is_some_and(|else_node| self.arm_jump_exposed(else_node.statements()));
        }
        if let Some(case_node) = node.as_case_match_node() {
            return case_node
                .conditions()
                .iter()
                .any(|condition| match condition.as_in_node() {
                    Some(in_node) => self.arm_jump_exposed(in_node.statements()),
                    None => false,
                })
                || case_node
                    .else_clause()
                    .is_some_and(|else_node| self.arm_jump_exposed(else_node.statements()));
        }
        if let Some(parentheses) = node.as_parentheses_node() {
            return match parentheses.body() {
                Some(body) => match body.as_statements_node() {
                    Some(statements) => self.arm_jump_exposed(Some(statements)),
                    None => self.jump_exposed(&body),
                },
                None => false,
            };
        }
        false
    }

    fn arm_jump_exposed(&self, statements: Option<StatementsNode<'_>>) -> bool {
        match statements.and_then(|statements| statements.body().iter().last()) {
            Some(last) => self.jump_exposed(&last),
            None => false,
        }
    }

    /// The expressions to wrap so the construct's normal completion is
    /// observed, or `None` when it cannot be observed at all. A statement that
    /// may not be wrapped is replaced by its arms, of which exactly one runs;
    /// an arm that is missing (an `if` with no `else`, whose fall-through
    /// carries no expression) makes the whole construct unobservable.
    fn probe_targets<'n>(&self, node: Node<'n>) -> Option<Vec<Node<'n>>> {
        if Self::is_jump(&node) {
            return Some(vec![node]);
        }
        if node.as_multi_write_node().is_some()
            || node.as_alias_method_node().is_some()
            || node.as_alias_global_variable_node().is_some()
            || node.as_undef_node().is_some()
        {
            return None;
        }
        if !self.jump_exposed(&node) {
            return Some(vec![node]);
        }
        if let Some(if_node) = node.as_if_node() {
            let mut targets = self.arm_targets(if_node.statements())?;
            match if_node.subsequent() {
                Some(subsequent) => match subsequent.as_else_node() {
                    Some(else_node) => targets.extend(self.arm_targets(else_node.statements())?),
                    None => targets.extend(self.probe_targets(subsequent)?),
                },
                None => return None,
            }
            return Some(targets);
        }
        if let Some(unless_node) = node.as_unless_node() {
            let mut targets = self.arm_targets(unless_node.statements())?;
            let else_node = unless_node.else_clause()?;
            targets.extend(self.arm_targets(else_node.statements())?);
            return Some(targets);
        }
        if let Some(case_node) = node.as_case_node() {
            let mut targets = Vec::new();
            for condition in case_node.conditions().iter() {
                let when_node = condition.as_when_node()?;
                targets.extend(self.arm_targets(when_node.statements())?);
            }
            targets.extend(self.arm_targets(case_node.else_clause()?.statements())?);
            return Some(targets);
        }
        if let Some(case_node) = node.as_case_match_node() {
            let mut targets = Vec::new();
            for condition in case_node.conditions().iter() {
                let in_node = condition.as_in_node()?;
                targets.extend(self.arm_targets(in_node.statements())?);
            }
            targets.extend(self.arm_targets(case_node.else_clause()?.statements())?);
            return Some(targets);
        }
        if let Some(begin) = node.as_begin_node() {
            let mut targets = match begin.else_clause() {
                Some(else_node) => self.arm_targets(else_node.statements())?,
                None => self.arm_targets(begin.statements())?,
            };
            let mut rescue = begin.rescue_clause();
            while let Some(clause) = rescue {
                targets.extend(self.arm_targets(clause.statements())?);
                rescue = clause.subsequent();
            }
            return Some(targets);
        }
        if let Some(parentheses) = node.as_parentheses_node() {
            let body = parentheses.body()?;
            return match body.as_statements_node() {
                Some(statements) => self.arm_targets(Some(statements)),
                None => self.probe_targets(body),
            };
        }
        None
    }

    fn arm_targets<'n>(&self, statements: Option<StatementsNode<'n>>) -> Option<Vec<Node<'n>>> {
        let last = statements.and_then(|statements| statements.body().iter().last())?;
        self.probe_targets(last)
    }

    /// Wrap the body's final statement so its normal completion is observed
    /// without changing the value of the construct. Returns false when the
    /// statement has no expression form to wrap (see
    /// [`Collector::jump_exposed`]).
    fn completion_probe(&mut self, last: Node<'_>, key: u64) -> bool {
        let Some(targets) = self.probe_targets(last) else {
            return false;
        };
        for target in &targets {
            self.wrap_completion(target, key);
        }
        true
    }

    /// One expression whose completion proves the construct completed.
    fn wrap_completion(&mut self, last: &Node<'_>, key: u64) {
        let location = last.location();
        let (start, end) = (location.start_offset(), location.end_offset());
        let arguments = if let Some(node) = last.as_return_node() {
            Some((node.keyword_loc(), node.arguments()))
        } else if let Some(node) = last.as_break_node() {
            Some((node.keyword_loc(), node.arguments()))
        } else {
            last.as_next_node()
                .map(|node| (node.keyword_loc(), node.arguments()))
        };
        if let Some((keyword, arguments)) = arguments {
            match arguments {
                Some(arguments) => {
                    let arguments_location = arguments.location();
                    let multiple = arguments.arguments().iter().count() > 1
                        || arguments
                            .arguments()
                            .iter()
                            .any(|argument| argument.as_splat_node().is_some());
                    let (open, close) = if multiple {
                        // `return a, b` already returns `[a, b]`.
                        (format!("{RUBY_PROBE_RECEIVER}.ok({key}, ["), "])")
                    } else {
                        (format!("{RUBY_PROBE_RECEIVER}.ok({key}, ("), "))")
                    };
                    self.depth += 1;
                    self.edit(
                        arguments_location.start_offset(),
                        EditRank::Opener,
                        open,
                        arguments_location.end_offset(),
                    );
                    self.edit(
                        arguments_location.end_offset(),
                        EditRank::Closer,
                        close.into(),
                        arguments_location.start_offset(),
                    );
                    self.depth -= 1;
                }
                None => self.edit(
                    keyword.start_offset(),
                    EditRank::StatementProbe,
                    format!("{RUBY_PROBE_RECEIVER}.ok0({key}); "),
                    end,
                ),
            }
            return;
        }
        if last.as_redo_node().is_some() || last.as_retry_node().is_some() {
            self.edit(
                start,
                EditRank::StatementProbe,
                format!("{RUBY_PROBE_RECEIVER}.ok0({key}); "),
                end,
            );
            return;
        }
        self.depth += 1;
        self.wrap(start, end, format!("{RUBY_PROBE_RECEIVER}.ok({key}, ("));
        self.depth -= 1;
    }

    fn rescue_modifier(&mut self, node: &RescueModifierNode<'_>) {
        let location = node.location();
        let (start, end) = (location.start_offset(), location.end_offset());
        let Some(id) = self.branch(
            start,
            end,
            "rescue-modifier",
            [
                ("success", "expression completed"),
                ("raised", "fallback used"),
            ],
        ) else {
            return;
        };
        let key = self.probe_key(ProbeTarget::Try {
            success: format!("{id}:success"),
            raised: format!("{id}:raised"),
            id,
            handlers: Vec::new(),
        });
        let expression = node.expression();
        let fallback_node = node.rescue_expression();
        let fallback = fallback_node.location();
        self.depth += 1;
        if Self::is_jump(&expression) {
            // `return x rescue y` has no value to wrap: probe the jump's
            // argument or the jump itself, as for a body's final statement.
            self.completion_probe(expression, key);
        } else {
            let expression = expression.location();
            self.wrap(
                expression.start_offset(),
                expression.end_offset(),
                format!("{RUBY_PROBE_RECEIVER}.ok({key}, ("),
            );
        }
        if Self::is_jump(&fallback_node) {
            // `rescue next` has no value either: `rescue (hm0(k); next)`.
            self.edit(
                fallback.start_offset(),
                EditRank::Opener,
                format!("({RUBY_PROBE_RECEIVER}.hm0({key}); "),
                fallback.end_offset(),
            );
            self.edit(
                fallback.end_offset(),
                EditRank::Closer,
                ")".into(),
                fallback.start_offset(),
            );
        } else {
            self.wrap(
                fallback.start_offset(),
                fallback.end_offset(),
                format!("{RUBY_PROBE_RECEIVER}.hm({key}, ("),
            );
        }
        self.depth -= 1;
    }

    /// A statement that leaves its frame or loop without producing a value.
    fn is_jump(node: &Node<'_>) -> bool {
        node.as_return_node().is_some()
            || node.as_break_node().is_some()
            || node.as_next_node().is_some()
            || node.as_redo_node().is_some()
            || node.as_retry_node().is_some()
    }

    fn def_node(&mut self, node: &DefNode<'_>) {
        let location = node.location();
        let (start, end) = (location.start_offset(), location.end_offset());
        let name = String::from_utf8_lossy(node.name().as_slice()).into_owned();
        let id = stable_id(self.file, "function", start, end, &name);
        if !self.point_ids.insert(id.clone()) {
            return;
        }
        self.push_point(&id, start, end, PointKind::Function, Some(name));
        let span = self.location_span(&location);
        self.methods.push(MethodKeyPlan {
            span,
            unshifted: span,
            id,
        });
        if let Some(body) = node.body()
            && let Some(begin) = body.as_begin_node()
        {
            self.begin_node(&begin, node.end_keyword_loc().map(|loc| loc.start_offset()));
        }
        if node.equal_loc().is_some()
            && let Some(body) = node.body()
            && let Some(statements) = body.as_statements_node()
        {
            for statement in statements.body().iter() {
                self.endless_bodies
                    .insert(statement.location().start_offset());
            }
        }
    }

    // -- finishing ----------------------------------------------------------

    /// Column shift the insertions cause on one line, for positions the
    /// runtime will read back from Ruby's `Coverage`. Insertions strictly
    /// inside a key's line range move whatever follows them. At a key's start,
    /// a probe moves an expression (it now follows the probe) but not a
    /// statement list whose first statement was probed, since the list still
    /// starts where the probe does; a list strictly containing the probed
    /// statement moves. An opener moves a key whose node it wraps (the node
    /// now sits inside the wrapper) and leaves alone a key whose node contains
    /// the wrapped one, since that node now begins with the wrapper. At a key's
    /// end, only a closer whose opener lies inside the key extends it: a list
    /// includes a wrapper around its last statement, an expression does not
    /// include the wrapper around itself. A point key follows everything
    /// inserted up to it, closers included.
    fn shifted(&self, span: PlanSpan, kind: KeyKind, edits: &[PendingEdit]) -> PlanSpan {
        let start_offset = self.line_starts[span.start[0] - 1] + span.start[1];
        let end_offset = self.line_starts[span.end[0] - 1] + span.end[1];
        let mut start_shift = 0;
        let mut end_shift = 0;
        for edit in edits {
            let (line, _) = self.line_column(edit.offset);
            let moves_start = edit.offset < start_offset
                || (edit.offset == start_offset
                    && match (edit.rank, kind) {
                        (_, KeyKind::Point) => true,
                        (EditRank::Closer, _) => false,
                        (EditRank::Opener, KeyKind::List) => end_offset < edit.scope,
                        (EditRank::Opener, KeyKind::Node) => end_offset <= edit.scope,
                        (_, KeyKind::List) => end_offset < edit.scope,
                        (_, KeyKind::Node) => true,
                    });
            let moves_end = edit.offset < end_offset
                || (edit.offset == end_offset
                    && match (edit.rank, kind) {
                        (_, KeyKind::Point) => true,
                        (EditRank::Closer, KeyKind::List) => edit.scope >= start_offset,
                        (EditRank::Closer, KeyKind::Node) => edit.scope > start_offset,
                        _ => false,
                    });
            if line == span.start[0] && moves_start {
                start_shift += edit.text.len();
            }
            if line == span.end[0] && moves_end {
                end_shift += edit.text.len();
            }
        }
        PlanSpan {
            start: [span.start[0], span.start[1] + start_shift],
            end: [span.end[0], span.end[1] + end_shift],
        }
    }

    fn finish(mut self) -> RubyFileObligations {
        let mut pending = std::mem::take(&mut self.edits);
        pending.sort_by(|left, right| {
            left.offset
                .cmp(&right.offset)
                .then(left.rank.cmp(&right.rank))
                .then(left.order.cmp(&right.order))
                .then(left.sequence.cmp(&right.sequence))
        });
        let branches = std::mem::take(&mut self.branches)
            .into_iter()
            .map(|mut branch| {
                branch.key.span = self.shifted(branch.key.span, branch.key.kind, &pending);
                branch
            })
            .collect::<Vec<_>>();
        let cases = std::mem::take(&mut self.cases)
            .into_iter()
            .map(|mut case| {
                for clause in &mut case.clauses {
                    clause.key.span = self.shifted(clause.key.span, clause.key.kind, &pending);
                }
                if let Some(no_match) = &mut case.no_match {
                    no_match.key.span =
                        self.shifted(no_match.key.span, no_match.key.kind, &pending);
                }
                case
            })
            .collect();
        let methods = std::mem::take(&mut self.methods)
            .into_iter()
            .map(|mut method| {
                method.span = self.shifted(method.span, KeyKind::Node, &pending);
                method
            })
            .collect();
        let edits = pending
            .into_iter()
            .map(|edit| Edit {
                offset: edit.offset,
                text: edit.text,
                rank: match edit.rank {
                    EditRank::Clause => "clause",
                    EditRank::StatementProbe => "statement",
                    EditRank::Opener => "opener",
                    EditRank::Closer => "closer",
                }
                .into(),
                scope: edit.scope,
            })
            .collect::<Vec<_>>();
        if let Some((id, line)) = self.begin_unmeasured.first() {
            let source = self
                .manifest
                .branches
                .iter()
                .find(|branch| &branch.id == id)
                .map(|branch| branch.source.lines().next().unwrap_or_default().to_owned())
                .unwrap_or_default();
            self.manifest.limitations.push(limitation(
                BEGIN_BODY_LIMITATION,
                self.file,
                *line,
                &source,
                "a begin body that is empty, or ends in a statement with no expression form, cannot have its completion observed",
            ));
        }
        self.manifest.unmeasured.sort();
        self.manifest.unmeasured.dedup();
        RubyFileObligations {
            manifest: self.manifest,
            plan: RubyFilePlan {
                probe_obligations: probe_obligations_of(&self.probes),
                edits,
                lines: self.lines,
                statement_offsets: self.statement_offsets,
                branches,
                methods,
                cases,
            },
            probes: self.probes,
        }
    }
}

fn limitation(id: &str, file: &str, line: usize, source: &str, reason: &str) -> serde_json::Value {
    json!({
        "id": id,
        "kind": "semantic-safety",
        "file": file,
        "line": line,
        "column": 0,
        "source": source,
        "reason": reason
    })
}

impl<'pr> Visit<'pr> for Collector<'_> {
    fn visit_statements_node(&mut self, node: &StatementsNode<'pr>) {
        if !self
            .expression_lists
            .contains(&node.location().start_offset())
        {
            self.statements(node);
        }
        ruby_prism::visit_statements_node(self, node);
    }

    fn visit_parentheses_node(&mut self, node: &ruby_prism::ParenthesesNode<'pr>) {
        if let Some(body) = node.body() {
            self.expression_lists.insert(body.location().start_offset());
        }
        ruby_prism::visit_parentheses_node(self, node);
    }

    fn visit_embedded_statements_node(&mut self, node: &ruby_prism::EmbeddedStatementsNode<'pr>) {
        if let Some(statements) = node.statements() {
            self.expression_lists
                .insert(statements.location().start_offset());
        }
        ruby_prism::visit_embedded_statements_node(self, node);
    }

    fn visit_if_node(&mut self, node: &IfNode<'pr>) {
        let offset = node.location().start_offset();
        if self.guard_nodes.contains(&offset) || self.elsif_nodes.contains(&offset) {
            self.depth += 1;
            ruby_prism::visit_if_node(self, node);
            self.depth -= 1;
            return;
        }
        if let Some(truthy) = self.literal_truth(node.predicate()) {
            // Ruby compiles only the live arm of `if false` / `if true` and
            // reports no branch for it; the dead arm is not code that can run.
            self.depth += 1;
            if truthy {
                if let Some(statements) = node.statements() {
                    self.visit_statements_node(&statements);
                }
            } else if let Some(subsequent) = node.subsequent() {
                match subsequent.as_if_node() {
                    Some(elsif) => self.visit_if_node(&elsif),
                    None => {
                        if let Some(else_node) = subsequent.as_else_node()
                            && let Some(statements) = else_node.statements()
                        {
                            self.visit_statements_node(&statements);
                        }
                    }
                }
            }
            self.depth -= 1;
            return;
        }
        // Ternaries have no `if` keyword; `elsif` is reached through
        // `subsequent` and handled by the parent's chain walk below.
        let kind = if node.if_keyword_loc().is_none() {
            "ternary"
        } else {
            "if"
        };
        self.if_node(node, kind);
        let mut subsequent = node.subsequent();
        while let Some(next) = subsequent {
            match next.as_if_node() {
                Some(elsif) => {
                    self.elsif_nodes.insert(elsif.location().start_offset());
                    self.if_node(&elsif, "elsif");
                    subsequent = elsif.subsequent();
                }
                None => break,
            }
        }
        self.depth += 1;
        // Children: predicate, statements, then the chain. Elsif nodes are
        // visited as children here too, but `if_node` deduplicates by
        // decision id.
        ruby_prism::visit_if_node(self, node);
        self.depth -= 1;
    }

    fn visit_unless_node(&mut self, node: &ruby_prism::UnlessNode<'pr>) {
        if self.guard_nodes.contains(&node.location().start_offset()) {
            self.depth += 1;
            ruby_prism::visit_unless_node(self, node);
            self.depth -= 1;
            return;
        }
        if let Some(truthy) = self.literal_truth(node.predicate()) {
            self.depth += 1;
            if truthy {
                if let Some(else_node) = node.else_clause()
                    && let Some(statements) = else_node.statements()
                {
                    self.visit_statements_node(&statements);
                }
            } else if let Some(statements) = node.statements() {
                self.visit_statements_node(&statements);
            }
            self.depth -= 1;
            return;
        }
        self.unless_node(node);
        self.depth += 1;
        ruby_prism::visit_unless_node(self, node);
        self.depth -= 1;
    }

    fn visit_while_node(&mut self, node: &WhileNode<'pr>) {
        self.loop_node(
            &node.location(),
            node.predicate(),
            node.statements(),
            node.is_begin_modifier(),
            false,
        );
        self.depth += 1;
        ruby_prism::visit_while_node(self, node);
        self.depth -= 1;
    }

    fn visit_until_node(&mut self, node: &UntilNode<'pr>) {
        self.loop_node(
            &node.location(),
            node.predicate(),
            node.statements(),
            node.is_begin_modifier(),
            true,
        );
        self.depth += 1;
        ruby_prism::visit_until_node(self, node);
        self.depth -= 1;
    }

    fn visit_for_node(&mut self, node: &ForNode<'pr>) {
        self.for_node(node);
        self.depth += 1;
        ruby_prism::visit_for_node(self, node);
        self.depth -= 1;
    }

    fn visit_case_node(&mut self, node: &CaseNode<'pr>) {
        self.case_node(node);
        self.depth += 1;
        ruby_prism::visit_case_node(self, node);
        self.depth -= 1;
    }

    fn visit_case_match_node(&mut self, node: &CaseMatchNode<'pr>) {
        self.case_match_node(node);
        self.depth += 1;
        ruby_prism::visit_case_match_node(self, node);
        self.depth -= 1;
    }

    fn visit_and_node(&mut self, node: &AndNode<'pr>) {
        let location = node.location();
        if !self.tree_logicals.contains(&location.start_offset()) {
            let left = node.left();
            self.value_logical("and", &left, location.start_offset(), location.end_offset());
        }
        self.depth += 1;
        ruby_prism::visit_and_node(self, node);
        self.depth -= 1;
    }

    fn visit_or_node(&mut self, node: &OrNode<'pr>) {
        let location = node.location();
        if !self.tree_logicals.contains(&location.start_offset()) {
            let left = node.left();
            self.value_logical("or", &left, location.start_offset(), location.end_offset());
        }
        self.depth += 1;
        ruby_prism::visit_or_node(self, node);
        self.depth -= 1;
    }

    fn visit_call_node(&mut self, node: &CallNode<'pr>) {
        if node.is_safe_navigation() {
            self.safe_navigation(node);
        }
        if let Some(block) = node.block()
            && let Some(block) = block.as_block_node()
            && let Some(receiver) = node.receiver()
            && !node.is_safe_navigation()
            && ITERATORS.contains(&node.name().as_slice())
        {
            self.iterator_loop(node, &receiver, &block);
        }
        self.depth += 1;
        ruby_prism::visit_call_node(self, node);
        self.depth -= 1;
    }

    fn visit_local_variable_or_write_node(
        &mut self,
        node: &ruby_prism::LocalVariableOrWriteNode<'pr>,
    ) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "or",
            location.start_offset(),
            location.end_offset(),
            Some(node.name().as_slice()),
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_local_variable_or_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_local_variable_and_write_node(
        &mut self,
        node: &ruby_prism::LocalVariableAndWriteNode<'pr>,
    ) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "and",
            location.start_offset(),
            location.end_offset(),
            Some(node.name().as_slice()),
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_local_variable_and_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_instance_variable_or_write_node(
        &mut self,
        node: &ruby_prism::InstanceVariableOrWriteNode<'pr>,
    ) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "or",
            location.start_offset(),
            location.end_offset(),
            Some(node.name().as_slice()),
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_instance_variable_or_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_instance_variable_and_write_node(
        &mut self,
        node: &ruby_prism::InstanceVariableAndWriteNode<'pr>,
    ) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "and",
            location.start_offset(),
            location.end_offset(),
            Some(node.name().as_slice()),
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_instance_variable_and_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_global_variable_or_write_node(
        &mut self,
        node: &ruby_prism::GlobalVariableOrWriteNode<'pr>,
    ) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "or",
            location.start_offset(),
            location.end_offset(),
            Some(node.name().as_slice()),
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_global_variable_or_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_class_variable_or_write_node(
        &mut self,
        node: &ruby_prism::ClassVariableOrWriteNode<'pr>,
    ) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "or",
            location.start_offset(),
            location.end_offset(),
            Some(node.name().as_slice()),
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_class_variable_or_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_call_or_write_node(&mut self, node: &ruby_prism::CallOrWriteNode<'pr>) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "or",
            location.start_offset(),
            location.end_offset(),
            None,
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_call_or_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_call_and_write_node(&mut self, node: &ruby_prism::CallAndWriteNode<'pr>) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "and",
            location.start_offset(),
            location.end_offset(),
            None,
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_call_and_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_index_or_write_node(&mut self, node: &ruby_prism::IndexOrWriteNode<'pr>) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "or",
            location.start_offset(),
            location.end_offset(),
            None,
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_index_or_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_index_and_write_node(&mut self, node: &ruby_prism::IndexAndWriteNode<'pr>) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "and",
            location.start_offset(),
            location.end_offset(),
            None,
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_index_and_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_constant_or_write_node(&mut self, node: &ruby_prism::ConstantOrWriteNode<'pr>) {
        let location = node.location();
        let value = node.value();
        self.op_assign(
            "or",
            location.start_offset(),
            location.end_offset(),
            None,
            &value,
        );
        self.depth += 1;
        ruby_prism::visit_constant_or_write_node(self, node);
        self.depth -= 1;
    }

    fn visit_def_node(&mut self, node: &DefNode<'pr>) {
        self.def_node(node);
        self.depth += 1;
        ruby_prism::visit_def_node(self, node);
        self.depth -= 1;
    }

    fn visit_begin_node(&mut self, node: &BeginNode<'pr>) {
        // Explicit `begin ... end`. Method and block bodies reach `begin_node`
        // through their hosts, which know the closing keyword; the branch id
        // dedupes the second visit.
        if node.begin_keyword_loc().is_some() {
            self.begin_node(node, None);
        }
        self.depth += 1;
        ruby_prism::visit_begin_node(self, node);
        self.depth -= 1;
    }

    fn visit_block_node(&mut self, node: &ruby_prism::BlockNode<'pr>) {
        if let Some(body) = node.body()
            && let Some(begin) = body.as_begin_node()
        {
            self.begin_node(&begin, Some(node.closing_loc().start_offset()));
        }
        self.depth += 1;
        ruby_prism::visit_block_node(self, node);
        self.depth -= 1;
    }

    fn visit_lambda_node(&mut self, node: &ruby_prism::LambdaNode<'pr>) {
        if let Some(body) = node.body()
            && let Some(begin) = body.as_begin_node()
        {
            self.begin_node(&begin, Some(node.closing_loc().start_offset()));
        }
        self.depth += 1;
        ruby_prism::visit_lambda_node(self, node);
        self.depth -= 1;
    }

    fn visit_rescue_modifier_node(&mut self, node: &RescueModifierNode<'pr>) {
        self.rescue_modifier(node);
        self.depth += 1;
        ruby_prism::visit_rescue_modifier_node(self, node);
        self.depth -= 1;
    }
}

/// Build the complete obligation manifest and probe plan for one Ruby file.
/// `next_probe` numbers probes uniquely across the whole project.
pub fn build_ruby_obligations(
    file: &str,
    source: &[u8],
    next_probe: &mut u64,
) -> Result<RubyFileObligations, RubyInstrumenterError> {
    let result = ruby_prism::parse(source);
    let errors = result
        .errors()
        .map(|error| error.message().to_owned())
        .collect::<Vec<_>>();
    if !errors.is_empty() {
        return Err(RubyInstrumenterError::Parse(errors.join("; ")));
    }
    let mut collector = Collector::new(file, source, next_probe);
    collector.visit(&result.node());
    if let Some(error) = collector.error.take() {
        return Err(error);
    }
    Ok(collector.finish())
}

/// Apply a plan's edits to the original source the way the runtime does.
pub fn apply_edits(source: &[u8], edits: &[Edit]) -> Vec<u8> {
    let mut output =
        Vec::with_capacity(source.len() + edits.iter().map(|e| e.text.len()).sum::<usize>());
    let mut cursor = 0;
    for edit in edits {
        output.extend_from_slice(&source[cursor..edit.offset]);
        output.extend_from_slice(edit.text.as_bytes());
        cursor = edit.offset;
    }
    output.extend_from_slice(&source[cursor..]);
    output
}

#[cfg(test)]
mod tests {
    use super::*;

    const SOURCE: &str = r#"class Shapes
  def classify(a, b, c)
    if a && (b || c)
      :yes
    elsif a
      :half
    else
      :no
    end
  end

  def loops(items, flag)
    total = 0
    items.each { |i| total += i if i > 2 && flag }
    while total > 100
      total -= 50
    end
    for x in items do total += x end
    total
  end

  def logical(a, b)
    x = a || b
    @cache ||= {}
    @cache[a] ||= b
    y = a ? 1 : 2; z = a&.size
    [x, y, z]
  end

  def guarded(s)
    Integer(s)
  rescue ArgumentError
    -1
  ensure
    @done = true
  end

  def cases(v)
    case v
    when 0 then :zero
    else :other
    end
    v.to_s rescue "bad"
  end
end
"#;

    #[test]
    fn discovers_obligations_with_stable_ids_and_newline_free_edits() {
        let mut probe = 0;
        let first = build_ruby_obligations("lib/shapes.rb", SOURCE.as_bytes(), &mut probe).unwrap();
        let mut probe = 0;
        let second =
            build_ruby_obligations("lib/shapes.rb", SOURCE.as_bytes(), &mut probe).unwrap();
        assert_eq!(first, second);
        let manifest = &first.manifest;
        let functions = manifest
            .points
            .iter()
            .filter(|point| point.kind == PointKind::Function)
            .map(|point| point.label.clone().unwrap())
            .collect::<Vec<_>>();
        assert_eq!(
            functions,
            ["classify", "loops", "logical", "guarded", "cases"]
        );
        let compound = manifest
            .decisions
            .iter()
            .find(|decision| decision.source == "a && (b || c)")
            .unwrap();
        assert_eq!(compound.conditions, ["a", "b", "c"]);
        assert_eq!(compound.kind, "if");
        assert!(
            manifest
                .decisions
                .iter()
                .any(|d| d.kind == "elsif" && d.conditions == ["a"])
        );
        assert!(manifest.decisions.iter().any(|d| d.kind == "ternary"));
        assert!(manifest.decisions.iter().any(|d| d.kind == "while"));
        for kind in [
            "for",
            "logical-or",
            "or-assign",
            "safe-navigation",
            "begin",
            "rescue-0",
            "case-when-0",
            "case-else",
            "rescue-modifier",
        ] {
            assert!(
                manifest.branches.iter().any(|branch| branch.kind == kind),
                "missing branch kind {kind}"
            );
        }
        for edit in &first.plan.edits {
            assert!(!edit.text.contains('\n'));
        }
        assert!(
            first
                .plan
                .edits
                .windows(2)
                .all(|pair| pair[0].offset <= pair[1].offset)
        );
        // `@cache[a] ||= b` is measured through arrival and right-side
        // probes; nothing is unmeasured.
        assert!(manifest.unmeasured.is_empty());
        assert!(manifest.limitations.is_empty());
    }

    #[test]
    fn transformed_source_keeps_line_count_and_carries_probes() {
        let mut probe = 0;
        let obligations =
            build_ruby_obligations("lib/shapes.rb", SOURCE.as_bytes(), &mut probe).unwrap();
        let transformed =
            String::from_utf8(apply_edits(SOURCE.as_bytes(), &obligations.plan.edits)).unwrap();
        assert_eq!(transformed.lines().count(), SOURCE.lines().count());
        assert!(
            transformed.contains("if $__supercov.d(0, ($__supercov.c(0, 0, (a)) && ($__supercov.c(0, 1, (b)) || $__supercov.c(0, 2, (c)))))"),
            "{transformed}"
        );
        assert!(transformed.contains("while $__supercov.w("));
        assert!(transformed.contains("for x in $__supercov.f("));
        assert!(transformed.contains("do $__supercov.fb("));
        assert!(transformed.contains("x = $__supercov.l("));
        assert!(transformed.contains("($__supercov.pre("));
        assert!(transformed.contains("||= ($__supercov.es("));
        assert!(transformed.contains("rescue Exception => __supercov_e; $__supercov.p("));
        assert!(transformed.contains("$__supercov.h("));
        assert!(transformed.contains("$__supercov.ok("));
        assert!(transformed.contains("rescue $__supercov.hm("));
        // The second statement on the `y = ...; z = ...` line gets a probe.
        assert!(transformed.contains("; $__supercov.s("));
        // Same-offset modifier bodies are proven by the stdlib branch key.
        assert!(
            obligations
                .plan
                .branches
                .iter()
                .any(|branch| !branch.hits.is_empty() && branch.key.group == "if")
        );
    }

    #[test]
    fn jumps_and_endless_bodies_take_wrapped_probes_and_literal_predicates_fold() {
        let source = "def inc(x) = x + 1\n\
                      [1].each { |v| y = Integer(v) rescue next }\n\
                      if false\n  dead\nelse\n  live\nend\n";
        let mut probe = 0;
        let obligations =
            build_ruby_obligations("lib/x.rb", source.as_bytes(), &mut probe).unwrap();
        let transformed =
            String::from_utf8(apply_edits(source.as_bytes(), &obligations.plan.edits)).unwrap();
        assert!(
            transformed.contains("def inc(x) = ($__supercov.s("),
            "{transformed}"
        );
        assert!(
            transformed.contains("rescue ($__supercov.hm0("),
            "{transformed}"
        );
        // `if false` has no branch and its dead arm no statements.
        assert!(
            obligations
                .plan
                .branches
                .iter()
                .all(|branch| branch.key.group != "if")
        );
        assert!(
            obligations
                .manifest
                .points
                .iter()
                .all(|point| point.source != "dead")
        );
        assert!(
            obligations
                .manifest
                .points
                .iter()
                .any(|point| point.source == "live")
        );
    }

    #[test]
    fn void_valued_last_statements_are_probed_arm_by_arm() {
        // Wrapping `if ... return ... else return ... end` in a value context
        // is a syntax error; each arm carries the completion probe instead.
        let source =
            "def m(c)\n  if c\n    return 1\n  else\n    return 2\n  end\nrescue\n  nil\nend\n";
        let mut probe = 0;
        let obligations =
            build_ruby_obligations("lib/v.rb", source.as_bytes(), &mut probe).unwrap();
        let transformed =
            String::from_utf8(apply_edits(source.as_bytes(), &obligations.plan.edits)).unwrap();
        assert_eq!(
            transformed.matches("$__supercov.ok(").count(),
            2,
            "{transformed}"
        );
        assert!(
            transformed.contains("return $__supercov.ok("),
            "{transformed}"
        );
        assert!(
            !obligations
                .manifest
                .unmeasured
                .iter()
                .any(|id| id.ends_with(":success")),
            "{:?}",
            obligations.manifest.unmeasured
        );
        assert!(!obligations.plan.probe_obligations.is_empty());
    }

    #[test]
    fn expressions_that_can_return_are_never_wrapped() {
        // `ok(k, (if a then return b end))` passes an expression that can jump
        // as an argument, which makes Ruby's compiler miscount its stack.
        let source = "def m(a, d)\n  begin\n    if a\n      return d\n    end\n  ensure\n    unlock\n  end\n  d\nend\n";
        let mut probe = 0;
        let obligations =
            build_ruby_obligations("lib/e.rb", source.as_bytes(), &mut probe).unwrap();
        let transformed =
            String::from_utf8(apply_edits(source.as_bytes(), &obligations.plan.edits)).unwrap();
        assert!(!transformed.contains("$__supercov.ok"), "{transformed}");
        assert!(
            obligations
                .manifest
                .unmeasured
                .iter()
                .any(|id| id.ends_with(":success")),
            "the begin's completion is declared instead"
        );
        // With both arms present the arms carry the probe and nothing is lost.
        let both = "def m(a, d)\n  begin\n    if a\n      return d\n    else\n      d + 1\n    end\n  ensure\n    unlock\n  end\nend\n";
        let mut probe = 0;
        let obligations = build_ruby_obligations("lib/f.rb", both.as_bytes(), &mut probe).unwrap();
        let transformed =
            String::from_utf8(apply_edits(both.as_bytes(), &obligations.plan.edits)).unwrap();
        assert!(
            transformed.contains("return $__supercov.ok("),
            "{transformed}"
        );
        assert!(
            !obligations
                .manifest
                .unmeasured
                .iter()
                .any(|id| id.ends_with(":success")),
            "{:?}",
            obligations.manifest.unmeasured
        );
    }

    #[test]
    fn stdlib_keys_shift_with_insertions_on_their_line() {
        let source = "def f(a, b)\n  x = 1 if a && b\nend\n";
        let mut probe = 0;
        let obligations = build_ruby_obligations("m.rb", source.as_bytes(), &mut probe).unwrap();
        let then_key = obligations
            .plan
            .branches
            .iter()
            .find(|branch| branch.key.branch == "then")
            .unwrap();
        // `x = 1` starts at column 2 and nothing is inserted before it.
        assert_eq!(then_key.key.span.start, [2, 2]);
        // Its end (column 7) is untouched too: insertions land in the
        // predicate, which comes after the body on this line.
        assert_eq!(then_key.key.span.end, [2, 7]);
        let else_key = obligations
            .plan
            .branches
            .iter()
            .find(|branch| branch.key.branch == "else")
            .unwrap();
        // The implicit else uses the whole if node, whose end moves right by
        // every inserted byte on that line.
        let inserted: usize = obligations
            .plan
            .edits
            .iter()
            .map(|edit| edit.text.len())
            .sum();
        assert_eq!(else_key.key.span.end, [2, 17 + inserted]);
        assert!(
            then_key.hits.len() == 1,
            "modifier body statement proven by the then key"
        );
    }

    #[test]
    fn rejects_invalid_ruby() {
        let mut probe = 0;
        assert!(matches!(
            build_ruby_obligations("m.rb", b"def x(\n", &mut probe),
            Err(RubyInstrumenterError::Parse(_))
        ));
    }
}