arcature-data 2026.2.0

//! The request-scoped N+1 [`Tracker`]: explicit, no hidden global.
//!
//! The caller constructs a `Tracker`, records query events with source
//! attribution as a request runs, and calls [`Tracker::report`] to get the
//! [`super::Report`]. The detection correlates per relation: a *parent load*
//! of N rows followed by multiple *child queries* accessing the same relation
//! is the textbook relation N+1, attributed to that relation with a
//! recommendation to eager-load it.
//!
//! # No global state
//!
//! There is no thread-local, task-local, or request-global tracker. The
//! application owns the `Tracker` by value in a typed request context and
//! passes it down explicitly (AGENTS.md §20). The internal events are guarded
//! by a `std::sync::Mutex` so a request that fans out across async tasks can
//! record safely — this is dev/CI-only code behind the `n1` feature, so the
//! lock overhead never reaches a production hot path.

use std::sync::Mutex;

use serde::Serialize;

use super::report::{Finding, FindingKind, Report};

/// The minimum number of per-row child queries for a relation (after a
/// multi-row parent load) that counts as an N+1. A single related fetch after
/// a parent load is not flagged — the signal is a *per-row* pattern, not any
/// repeated statement (PROGRAM.md AP2.1-6: "not every repeated statement").
pub const DEFAULT_THRESHOLD: usize = 2;

/// A recorded query event used by the N+1 analyzer.
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub enum QueryEvent {
    /// A parent query loaded `row_count` rows of a relation (e.g. all posts
    /// for a user). The `relation` names the parent entity's relation that
    /// loaded the rows (e.g. `"User.posts"`); `query` is the source signature.
    Parent {
        relation: String,
        query: String,
        row_count: usize,
    },
    /// A child query accessed a relation on a single parent row (e.g. one
    /// post's author). The `relation` matches the parent load's relation so
    /// the analyzer can correlate them.
    Child { relation: String, query: String },
}

/// A request-scoped N+1 tracker. Construct explicitly; do not share via a
/// global. See the module docs for the no-global-state invariant.
pub struct Tracker {
    events: Mutex<Vec<QueryEvent>>,
    threshold: usize,
}

impl Tracker {
    /// Construct a tracker with the default threshold
    /// ([`DEFAULT_THRESHOLD`]).
    #[must_use]
    pub fn new() -> Self {
        Self::with_threshold(DEFAULT_THRESHOLD)
    }

    /// Construct a tracker with a custom minimum per-row child-query
    /// threshold. `threshold` of `1` flags any child query after a multi-row
    /// parent load; higher values require a stronger per-row signal.
    #[must_use]
    pub fn with_threshold(threshold: usize) -> Self {
        Self {
            events: Mutex::new(Vec::new()),
            threshold,
        }
    }

    /// Record a parent query that loaded `row_count` rows of `relation`.
    pub fn record_parent_load(&self, relation: &str, query: &str, row_count: usize) {
        if let Ok(mut events) = self.events.lock() {
            events.push(QueryEvent::Parent {
                relation: relation.to_owned(),
                query: query.to_owned(),
                row_count,
            });
        }
    }

    /// Record a child query that accessed `relation` on a single parent row.
    pub fn record_child_query(&self, relation: &str, query: &str) {
        if let Ok(mut events) = self.events.lock() {
            events.push(QueryEvent::Child {
                relation: relation.to_owned(),
                query: query.to_owned(),
            });
        }
    }

    /// The number of recorded events (for tests and diagnostics).
    #[must_use]
    pub fn event_count(&self) -> usize {
        self.events.lock().map(|events| events.len()).unwrap_or(0)
    }

    /// Analyze the recorded events and return the N+1 [`Report`].
    ///
    /// For each relation, if a parent load of more than one row was followed
    /// by at least `threshold` child queries for that relation, emit a
    /// [`Finding`] attributing the N+1 to that relation and recommending
    /// eager loading. The analysis is deterministic and runs in linear time
    /// over the event stream.
    #[must_use]
    pub fn report(&self) -> Report {
        let Ok(events) = self.events.lock() else {
            return Report::default();
        };
        // For each relation, track: did a parent load of >1 row occur, and
        // how many child queries followed it. Child queries before any parent
        // load are ignored (they are not a post-list N+1).
        use std::collections::HashMap;
        #[derive(Default)]
        struct Acc {
            parent_seen: bool,
            parent_query: String,
            parent_rows: usize,
            child_queries: usize,
        }
        let mut by_relation: HashMap<String, Acc> = HashMap::new();
        for event in events.iter() {
            match event {
                QueryEvent::Parent {
                    relation,
                    query,
                    row_count,
                } => {
                    let acc = by_relation.entry(relation.clone()).or_default();
                    acc.parent_seen = true;
                    acc.parent_query = query.clone();
                    acc.parent_rows = *row_count;
                    // A new parent load resets the child counter for this
                    // relation: N+1 is measured against the most recent list.
                    acc.child_queries = 0;
                }
                QueryEvent::Child { relation, query } => {
                    let acc = by_relation.entry(relation.clone()).or_default();
                    acc.child_queries += 1;
                    // Record the last child query signature for attribution
                    // (the analyzer names the per-row pattern; the first
                    // child query signature is representative).
                    if acc.child_queries == 1 {
                        // Store on the acc via the query — keep it minimal.
                        let _ = query;
                    }
                }
            }
        }
        let mut findings = Vec::new();
        for (relation, acc) in by_relation {
            if acc.parent_seen && acc.parent_rows > 1 && acc.child_queries >= self.threshold {
                findings.push(Finding {
                    relation: relation.clone(),
                    kind: FindingKind::RelationPerRow,
                    parent_query: acc.parent_query,
                    child_queries: acc.child_queries,
                    recommendation: format!(
                        "eager-load `{relation}` instead of per-row access \
                         (parent loaded {rows} rows, {children} per-row child queries fired)",
                        rows = acc.parent_rows,
                        children = acc.child_queries
                    ),
                });
            }
        }
        // Deterministic order: sort by relation name so the report is stable
        // across runs (PROGRAM.md "Static explanation for automatic behavior").
        findings.sort_by(|a, b| a.relation.cmp(&b.relation));
        Report { findings }
    }
}

impl Default for Tracker {
    fn default() -> Self {
        Self::new()
    }
}