1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
//! Development/CI N+1 detection (PROGRAM.md AP2.1-6).
//!
//! A request-scoped [`Tracker`] records query events with **source
//! attribution** and reports likely relation N+1 patterns. The detection is:
//!
//! - **Per-relation, per-query-pattern**, not a dumb global counter. A
//! [`Report`] carries [`Finding`]s, each naming the relation that triggered
//! the N+1 (e.g. `"User.posts"`), the query that loaded the parent rows, and
//! the query that re-fired per parent row.
//! - **Zero production hot-path overhead when the `n1` feature is off.** This
//! entire module is `#[cfg(feature = "n1")]`; the crate's query/transaction
//! APIs have no `n1`-gated call sites in the default build, so the tracker
//! and its recording calls compile away to nothing on a production build.
//! - **Useful diagnostics.** The report prints a human-readable explanation
//! and serializes to JSON for `arc` tooling, recommending eager loading.
//!
//! # Why this is not a fake global counter
//!
//! The tracker is **constructed explicitly per request scope** (the caller owns
//! it) and records `(parent_relation, parent_query_signature, child_count)` so
//! the analyzer can detect the signature pattern: one parent query producing N
//! children, followed by N+1 child queries keyed on the parent relation. A
//! naive counter would fire on any repeated statement (e.g. a loop over users
//! in a batch job); the attribution-based detector fires only when a *relation
//! access* (e.g. `user.posts`) causes a per-row re-query — the actual N+1 bug
//! class PROGRAM.md names ("identify likely relation N+1, recommend eager
//! loading; not every repeated statement").
//!
//! # No hidden global
//!
//! There is no thread-local, task-local, or request-global tracker. The
//! caller constructs the [`Tracker`], passes it down explicitly, and calls
//! [`Tracker::report`] when done (AGENTS.md §20; PROGRAM.md AP2.1-6). The
//! recommended integration is a typed request context in the application that
//! owns the `Tracker` by value.
pub use ;
pub use ;