cpp_ls 0.3.0

//! # AnalysisState — the analysis session and the buffers, behind a read-write lock
//!
//! One [`Session`] for the workspace: created when the client says where the workspace is, read by every request
//! under a read lock, written by the notification worker under a write lock. A query does **not** clone the analysis
//! to run — a read guard *is* the session, and the query reads through it while other readers do the same.
//!
//! # Why the session is an `Option`, and what a query answers without one
//!
//! The server's two halves learn different things at different times: `initialize` builds this state, and
//! `initialized` (or the first `workspace/didChangeWorkspaceFolders`) is what names a root directory — and the root
//! is what a session is opened over, because opening one runs the compiler and reads `compile_commands.json`
//! (`Session::open`). So there is a window in which a request can arrive with no analysis behind it, and the answer
//! there is [`RequestOutcome::Missing`] with a log line: "the analysis has not been opened" is a true statement, and
//! an empty result set would be a false one. The same rule the analysis layer applies to `Unknown` applies here.
//!
//! # Why the providers are held here as well as by the session
//!
//! Because there are two users of one chain: the session owns a handle to it (that is how it reads a file), and the
//! client's notifications arrive with text that has to reach the same chain. `SessionFiles` is a **handle** — the
//! buffers are a map behind a lock that clones share — so `files` and `documents` here and the session's copy are
//! the same files, not copies of them. See `cpp_code_analysis::session`'s module documentation.
//!
//! # What a request waits for, and the `settle` that used to make it worse
//!
//! ```text
//!   a request's wait  =  (the work the request does)
//!                     +  (the time until the lock the request needs is free)
//! ```
//!
//! The second term has two sources, and both were removed:
//!
//! * **the pump's write**, which is what the pump holds the session for while inserting. Every part of a drain that
//!   is not an insert has been moved out from under it — the parse ([`cpp_code_analysis::Session::prepare_a_wave`]),
//!   the second pass ([`cpp_code_analysis::Session::prepare_the_drain`]), the macro environments and the cook's
//!   materials ([`cpp_code_analysis::Session::materials_for`]) — so a write is 0–25 ms measured, where a slice that
//!   committed *no files at all* used to hold it for 572 ms;
//! * **the pump's read**, which it holds while parsing and which a request's *write* must wait for. This is the one
//!   that cannot be tuned away: parsing has to read the index. What removed it is that a request **no longer asks for
//!   the write lock when it has nothing to write** — see [`AnalysisState::prepare`] and [`AnalysisState::catch_up`],
//!   which ask a question about one file under the read lock and take the write one only when the answer is "there is
//!   work".
//!
//! There used to be a third, and it is worth keeping on the record because it was written twice: `settle` asked
//! whether the **whole project's** indexing queue had drained and waited up to two seconds for the answer to become
//! yes. Every answer in this server is built to **degrade rather than lie** — a name whose declaration has not been
//! read yet is skipped — so an index that is still filling gives *fewer* items and never wrong ones, and on its own
//! that makes the first minute of a session look broken: measured on a report, opening a file showed **no inlay hints
//! at all** and a completion list of nothing but keywords while hover worked.
//!
//! It was asked in eight handlers, and the question it asked was the wrong size:
//!
//! ```text
//!   what the wait was a question about     the whole project
//!   what the answer is a statement about   one file
//! ```
//!
//! Measured over the wire, twelve completions fired from `didOpen`: **988 / 536 / 1443 / 877 / 542 / 734 / 584 /
//! 1479 / 532 / 728 / 353 / 4 ms**. With the wait gone and the per-file reads in its place — the file's text, the
//! file's summary and the includes nobody has read, the modules it imports — they take **11 / 8 / 4 / 9 / 0 … 7 ms**,
//! with the list the same length or longer at every attempt. clangd states the rule this follows in as many words:
//! *"we don't wait for it to be up-to-date. Since completion is extremely time sensitive, it just uses whichever is
//! immediately available."*
//!
//! An empty popup is still the symptom to watch for. The fix for it is the hot set and the per-file reads, **never a
//! global wait**.

/// **How many files one pull request may index** — the bound that was missing, and the 102 seconds it cost.
///
/// [`Session::index_everything`] loops until the queue is **empty**, so a caller that asks for it asks for the whole
/// project. A pull request did exactly that, and the budget warning caught what it means:
///
/// ```text
/// 20:22:22  index slice: prepared 128, committed 32, write lock held 563 ms, 1258 left
/// 20:24:05  `prepare a file a pull request named` held the analysis for 102700 ms
/// 20:24:09  index slice: prepared 1, committed 1, write lock held 0 ms, 1 to cook, 0 left
/// ```
///
/// The pump was 1 258 files from finished and the pull drained all of them in one closure — **102 seconds of write
/// hold**, during which every keystroke, hover and completion in the editor waited. The queue was empty when the
/// pump got control back, which is why its own line says `0 left`.
///
/// **The number is larger than the pump's own slice on purpose.** A file cannot be cooked until its include chain
/// has been read, so a pull that stops too early cannot answer at all — and an empty answer is the defect this
/// function exists to fix. The pump finishes whatever is left within the second, and the pull no longer holds the
/// editor for a minute and a half.
///
/// **Twenty-four, and it was five hundred** — a number about a *project*, applied to a queue that is not the file's
/// include chain: while a module was being read the queue held the standard library's four hundred files, and every
/// pull drained them. Measured on `test_module` with `src/std_module_demo.cpp` open (`import std;`):
///
/// ```text
///                                              500        24
/// first pull after opening the file            1.95 s     271 ms
/// longest update hold in the session           1 815 ms   86 ms
/// the completion that follows                  153 ms     30 ms
/// ```
const PREPARE_INDEX_SLICE: usize = 24;

use std::path::PathBuf;
use std::sync::{Arc, RwLock, RwLockReadGuard};
use std::time::Duration;

use cpp_code_analysis::{DiskFiles, OpenDocuments, Session, SessionFiles, WatchFilter};
use tokio::sync::{Mutex, Notify, Semaphore};

use crate::context::RequestOutcome;

pub struct AnalysisState {
    /// The session, from the moment the workspace root is known. `None` before that; see the module documentation.
    inner: Arc<RwLock<Option<Session<DiskFiles>>>>,
    /// The provider chain a session is opened over, and the handle this state keeps after it is.
    files: SessionFiles<DiskFiles>,
    /// How many queries may read at once.
    blocking_permits: Arc<Semaphore>,
    file_read_gate: Arc<Mutex<()>>,
    /// Held for reading by a query and for writing by an update, so that an update waits for the queries already
    /// running rather than interleaving with them. That is the whole reason it is separate from `inner`'s own lock:
    /// the write lock is taken *before* the blocking hop, which is what keeps a notification from being overtaken.
    gate: Arc<tokio::sync::RwLock<()>>,
    /// **The longest an update has held `inner`**, in milliseconds — see [`AnalysisState::update`].
    worst_write_hold: Arc<std::sync::atomic::AtomicU64>,
    /// "The queue has work in it" — how an edit reaches the task that reads.
    work: Arc<Notify>,
}

/// **How long an update may hold the analysis before it is a defect.**
///
/// A query and an update take the same lock, so this is a bound on how long any request can be made to wait by the
/// background: not on average, not usually — **by construction**, because there is no other lock on the path and a
/// request that is slow for another reason is slow inside its own work.
///
/// The number is chosen from what the work is: an update **inserts what a step produced**, and inserting is a map
/// write per declaration. Measured, the insert half of an index slice is 8–19 ms. Fifty leaves room for a slice
/// that has to grow a table and still fails a closure that parses a file, walks a unit, or runs a second pass.
pub const WRITE_BUDGET: Duration = Duration::from_millis(50);

/// **How long a read-only query may take before it is worth a line in the log.**
///
/// The read side's counterpart of [`WRITE_BUDGET`], and deliberately the same number: a keystroke's budget is around
/// 16 ms and this server's answer to one is a query, so a query over fifty milliseconds is either waiting for
/// something or doing too much — and [`AnalysisState::run_blocking`] says which, in four numbers that fail
/// separately.
///
/// Reported rather than enforced: a query's own work is allowed to be as large as the question is (a completion
/// after `std::` collects thousands of declarations), and the point of the line is to make that visible rather than
/// to bound it.
pub const QUERY_BUDGET: Duration = Duration::from_millis(50);

impl AnalysisState {
    pub fn new() -> Self {
        let documents = OpenDocuments::new();
        let files = SessionFiles::new(documents, DiskFiles);
        Self {
            inner: Arc::new(RwLock::new(None)),
            files,
            gate: Arc::new(tokio::sync::RwLock::new(())),
            blocking_permits: Arc::new(Semaphore::new(Self::analysis_parallelism())),
            file_read_gate: Arc::new(Mutex::new(())),
            worst_write_hold: Arc::new(std::sync::atomic::AtomicU64::new(0)),
            work: Arc::new(Notify::new()),
        }
    }

    /// Read a file in and hold it, so that the read-only queries can see it.
    ///
    /// # Why a request needs this, and why it is not part of the query
    ///
    /// The VFS holds a file's text and its line index, and it has **no lock of its own**: changing what is held
    /// takes `&mut Session`, so a *query* — which runs under this state's read lock, in parallel with other queries
    /// — can only look at what is held. Filling the table is the writer's job, and two writers already do it: the
    /// notification path (`didOpen`/`didChange` hold the client's buffers, `didClose` closes them) and the indexer
    /// (every file it reads, it holds).
    ///
    /// This method is the remaining gap: a request can be about a file nothing has read yet — a client asking for
    /// diagnostics of a file it never opened. So the handler asks for the file **before** the query; the write lock
    /// is held for as long as one file takes to read, and the query itself stays a read, in parallel with every
    /// other request. (A query that loaded what it needed would take `&mut Session` and serialize all of them, which
    /// is the trade this exists to avoid.)
    pub async fn prepare(&self, path: &std::path::Path) -> bool {
        let whole = std::time::Instant::now();
        let answer = self.prepare_inner(path).await;
        if whole.elapsed().as_millis() >= 50 {
            log::warn!("prepare {} took {:?}", path.display(), whole.elapsed());
        }
        answer
    }

    async fn prepare_inner(&self, path: &std::path::Path) -> bool {
        // **The shortcut that matters, and it is the ordinary case.** The file a request is about is normally one the
        // editor has open, so the VFS already holds its text and its cooked reading is either built or already asked
        // for — which is exactly the state in which the two steps below would each do nothing. Asking is a read, and
        // a read takes the lock the pump takes **as a reader**, so it does not wait for the pump's parse; the write
        // would.
        //
        // Measured over the wire on the latency fixture before this: a completion spent **9–1147 ms** here and every
        // millisecond of it was the queue — the work is a `HashSet` lookup and a map lookup.
        //
        // `false` from the snapshot (no workspace open) falls through to the write, which answers `Missing` the same
        // way it always did.
        //
        // **A hypothesis tried here and withdrawn, with its measurement.** The shortcut's condition is "the file is
        // held and its summary is current", which is *not* the same as "its rendering exists" — so it looked like the
        // reason a file the client opened never got cooked, and that in turn looked like the reason several handshake
        // tests report `"result":null` on every retry for thirty seconds. Adding `&& session.view(path).is_some()` to
        // the condition changed the handshake result **not at all** (6 passed, 17 failed, before and after), so the
        // hypothesis is wrong — and the condition costs a `view()` call on the hot path the shortcut exists for.
        // Withdrawn rather than kept as a plausible-looking change that nothing measured.

        // **The shortcut those paragraphs describe — and which was not here to take.**
        //
        // Everything above is the argument for not asking for the write lock, and the function then asked for it
        // unconditionally: `update_session` is a *write*, and the pump holds the session for reading for a slice (50 ms
        // is the budget line, and the log warns when a request holds the lock that long). Measured on
        // `EmmyLuaCodeStyle` with `CPPLS_TRACE_CODE_ACTION=1`: `codeAction` took **56 ms, of which `prepare` was
        // 54 ms** — and the fix provider itself was **14 µs**. The handler was not slow; it was queueing.
        //
        // Check the rendering without constructing a parsed view on this path.
        if self
            .with_snapshot(|session| {
                session.files().held(path).is_some_and(|file| file.open)
                    || session.has_rendering(path)
            })
            .unwrap_or(false)
        {
            return true;
        }

        let path = path.to_path_buf();
        let queued = self
            .update_session("prepare a file a request named", move |session| {
                let loaded = session.load(&path).is_some();
                // **A file a request is about gets its cooked reading** — and this is the only place that knows which
                // file a request named. Not "cook it now": the query below answers from the reading that exists, and
                // the *next* request gets the compiler's reading, which is what `isIncomplete` tells a client to come
                // back for. The session's rule is that a reading is built when something looks at the file; this is
                // the "something" for everything the editor did not open.
                if loaded {
                    session.want_cooked_reading(&path);
                }
                loaded
            })
            .await
            .unwrap_or(false);

        // **And the consumer is woken, which it was not.**
        //
        // `want_cooked_reading` puts a file in the cooking queue; the queue is a value, and something has to *look*
        // at it. The pump is woken by the notification paths (`didOpen`, `didChange`, a watched file) and by
        // nothing else — so a file this function queued sat in the queue until the reader happened to type, and the
        // request that was supposed to be answered "next time" was answered `None` for as long as nobody edited
        // anything. The deferral's own contract is *"the next request gets the compiler's reading"*; without this
        // wake there was no next event to get it on.
        //
        // Woken after the write above, not inside it: `wake` is a `Notify` and the queue is the message, so it
        // carries no data and cannot be lost by arriving early — which is the arrangement that comment describes.
        if queued {
            self.wake();
        }
        queued
    }

    /// **The file in front of the analysis, without taking the write lock when it already is.**
    ///
    /// Hover answers from the file's **own text** — `handlers::hover` says so and asks `view_of_the_file`, whose
    /// parse is of the written text — so what it needs is the buffer and the file's summary, never a cooked
    /// rendering. [`AnalysisState::prepare`] takes the write lock to load the file and queue that cook, and during a
    /// cold index the write lock is the pump's: the request waits behind a slice of somebody else's work.
    ///
    /// Measured over the wire on an 831-file project (neovim, release build), three files opened and then hovered six
    /// times each:
    ///
    /// ```text
    ///                       first hover     after it
    ///   charset.c           1 103 ms        12–34 ms
    ///   mbyte.c               193 ms        24–36 ms
    ///   fs.c                   77 ms        15–36 ms
    /// ```
    ///
    /// The first number is the queue, not the query: every later hover on the same file is a few milliseconds of real
    /// work. A file whose summary is already current — the ordinary case, because the editor has it open and
    /// `didOpen` read it in — is answered by the read-only path below and never queues.
    pub async fn prepare_for_a_read(&self, path: &std::path::Path) -> bool {
        if let Ok(session) = self.inner.try_read()
            && let Some(session) = session.as_ref()
            && session.index().summary(path).is_some()
        {
            // **The file this request is about is one the second pass may refine** — a start no longer refines the
            // project (`docs/indexing-design.md`, phase 0), so asking must happen here, under the read lock, and the
            // recording is behind its own lock for exactly that reason. `wake` is what tells the pump there is work:
            // without it the ask sits in the set until somebody types.
            session.want_refinement(path);
            self.wake();
            return true;
        }

        self.prepare(path).await
    }

    /// **Read the file a request is about in, if the analysis is behind it** — the request path's form of
    /// [`Session::catch_up`].
    ///
    /// # Why this is not just `update_session(|s| s.catch_up(path))`
    ///
    /// Because the lock is the whole cost. The pump parses a project's include closure while **holding the session
    /// for reading** — measured, a hundred milliseconds a section and sometimes more than a second — and a request
    /// that asks for the write lock waits for the section in flight. `catch_up`'s own work is conditional: the file
    /// when an edit dropped its summary, and the includes the index has never read. For the ordinary request both
    /// are empty and the call is a `HashSet` lookup, paid for with a second of queueing.
    ///
    /// Measured over the wire on the latency fixture, with the same shortcut already in place for
    /// [`AnalysisState::prepare`]: `catch_up` cost **0–1108 ms** on a file whose summary was current.
    ///
    /// The check is a **read**, and a read does not wait for the pump's parse — only a write does. See
    /// [`Session::needs_catching_up`] for why the answer is exact rather than a guess.
    pub async fn catch_up(&self, path: &std::path::Path) {
        const MAX_FILES: usize = 9;
        for _ in 0..MAX_FILES {
            let Some(next) = self.next_file_for_catch_up(path).await else {
                return;
            };
            self.read_queued_file(&next).await;
        }
        self.wake();
    }

    async fn next_file_for_catch_up(&self, path: &std::path::Path) -> Option<PathBuf> {
        let immediate = match self.inner.try_read() {
            Ok(session) => Some(session.as_ref().map(|session| {
                (
                    session.needs_catching_up(path),
                    session.next_file_to_catch_up(path),
                )
            })),
            Err(_) => None,
        };
        let (needs_work, next) = match immediate {
            Some(state) => state,
            None => {
                let path = path.to_path_buf();
                self.run_blocking(move |session| {
                    Some((
                        session.needs_catching_up(&path),
                        session.next_file_to_catch_up(&path),
                    ))
                })
                .await
            }
        }?;
        if !needs_work {
            return None;
        }
        if next.is_some() {
            return next;
        }
        let path = path.to_path_buf();
        self.update_session("queue an unread include", move |session| {
            session.ensure_file_to_catch_up(&path)
        })
        .await
        .flatten()
    }

    pub async fn read_queued_file(&self, path: &std::path::Path) -> bool {
        let guard = self.file_read_gate.clone().lock_owned().await;
        let path = path.to_path_buf();
        let gathered = self
            .run_blocking(move |session| Some((session.gather_a_file_read(&path), guard)))
            .await;
        let Some((Some(materials), guard)) = gathered else {
            return false;
        };
        let prepared = tokio::task::spawn_blocking(move || (materials.read(), guard)).await;
        let (prepared, _guard) = match prepared {
            Ok(prepared) => prepared,
            Err(error) if error.is_panic() => std::panic::resume_unwind(error.into_panic()),
            Err(error) => {
                log::error!("the background file read failed: {error}");
                return false;
            }
        };
        let committed = self
            .update_session("commit a file read", move |session| {
                session.commit_a_file_read(prepared)
            })
            .await
            .unwrap_or(false);
        if committed {
            self.wake();
        }
        committed
    }

    pub async fn render_cooks(
        &self,
        cooks: Vec<cpp_code_analysis::session::DetachedCook<DiskFiles>>,
    ) -> Vec<cpp_code_analysis::session::RenderedCook> {
        if cooks.is_empty() {
            return Vec::new();
        }
        let permit = match self.blocking_permits.clone().acquire_owned().await {
            Ok(permit) => permit,
            Err(error) => {
                log::error!("cannot schedule rendering: {error}");
                return Vec::new();
            }
        };
        match tokio::task::spawn_blocking(move || {
            let _permit = permit;
            cooks.into_iter().filter_map(|cook| cook.render()).collect()
        })
        .await
        {
            Ok(rendered) => rendered,
            Err(error) if error.is_panic() => std::panic::resume_unwind(error.into_panic()),
            Err(error) => {
                log::error!("rendering failed: {error}");
                Vec::new()
            }
        }
    }

    /// Tell the indexing pump that the queue has work in it.
    ///
    /// Called after a notification has changed what the analysis should read. The engine has no threads and no
    /// scheduler on purpose (`Session::advance` is "one file per call, and the caller decides how much"), so
    /// *something* in this layer has to be the caller that keeps calling — this is how that task is told there is
    /// a reason to. `Notify` rather than a channel because the signal carries no data: the queue is the message.
    pub fn wake(&self) {
        self.work.notify_one();
    }

    /// **Read one whole program — the one part of a slice whose cost must not be paid under any lock.**
    ///
    /// A program read is a walk, a cook of every file in include order, a parse of the whole program and a sweep of
    /// every declaration in it: **5.09 s** for a 159-file, 7.07 MB program, and 63 ms for the same program from the
    /// database. Of that, the walk and the closure's texts are **44 ms** and they are the only part that needs the
    /// session — so the three phases are priced completely differently, and this is where they are taken apart:
    ///
    /// ```text
    /// Session::gather_a_unit_read      under the read lock   44 ms    the walk, the texts, two cache reads
    /// UnitReadMaterials::read_the_program   NO LOCK         4.9 s     the cook, the parse, the sweep
    /// Session::commit_a_program        under the write lock a few ms  one insert_cooked per file
    /// ```
    ///
    /// # Why the middle phase runs on a blocking thread of its own
    ///
    /// Because it is the session's **only** indivisible piece of work, and the walk's 44 ms is the
    /// only part that has to hold the lock a keystroke waits for. Nothing about it needs an `async`
    /// context, so it must not occupy an `async` one: a 4.9 second task on the runtime would take
    /// the executor away from every request in flight — the same reason `run_blocking` exists.
    ///
    /// Returns whether a program was attempted. `false` when none was owed, or when the clock
    /// ([`cpp_code_analysis::Session::the_program_to_read`]) or the size budget said no.
    pub async fn read_a_program(&self) -> bool {
        let Some(Some((root, revision))) = self.with_snapshot(|session| {
            session
                .the_program_to_read()
                .map(|root| (root, session.revision()))
        }) else {
            return false;
        };

        // **The cheap half under the lock that is already taken for reads**, beside whatever other queries are doing.
        let gathering = root.clone();
        let materials = self
            .run_blocking(move |session| session.gather_a_unit_read(&gathering))
            .await;

        // **The expensive half with no lock at all.** `spawn_blocking` rather than the analysis pool: this work is
        // the background's, and it must not be one of the permits a request waits for.
        let prepared = match materials {
            Some(materials) => {
                match tokio::task::spawn_blocking(move || materials.read_the_program()).await {
                    Ok(prepared) => prepared,
                    Err(error) if error.is_panic() => std::panic::resume_unwind(error.into_panic()),
                    Err(error) => {
                        log::error!("the background program read failed: {error}");
                        return false;
                    }
                }
            }
            None => None,
        };

        // **And the inserts, under the writer.** The root is marked read even when the read declined, so a program
        // that cannot be built is not chosen again on the next wake.
        let read = self
            .update_session("read a program", move |session| {
                if !session.is_current(&revision) {
                    log::debug!("discarding a program read from an older session revision");
                    return None;
                }
                session.commit_a_program(&root, prepared)
            })
            .await
            .flatten();

        // **One line, because this is the most expensive thing the server does unprompted** — and the reader's log is
        // where "why is a core busy for five seconds after I stop typing" is answered. Silent when the *insert* is
        // all that happened (a program the database already had), which is the cheap case.
        if let Some(reading) = &read {
            log::info!(
                "read a program as one piece: {} file(s), {} token(s), {} error(s) — their declarations are the \
                 compiler's reading now",
                reading.files,
                reading.tokens,
                reading.errors
            );
        }
        read.is_some()
    }

    /// Wait for a wake-up, or for `timeout` to pass.
    ///
    /// Returns whether a wake-up arrived. The timeout is **insurance, not the mechanism**: `Notify` stores one
    /// permit, so a wake that arrives before this call is not lost — but a stall would leave the index empty for
    /// the rest of the session, and one lock acquisition a second is a cheap way never to find out.
    pub async fn wait_for_work(&self, timeout: Duration) -> bool {
        tokio::time::timeout(timeout, self.work.notified())
            .await
            .is_ok()
    }

    /// Run `f` against the live session, or answer `None` when no workspace has been opened.
    ///
    /// **The read happens on a blocking-capable thread.** The lock is synchronous, and this is called from `async`
    /// handlers: taking it directly parks a runtime worker for as long as a writer holds it, which is the one thing an
    /// async server must not do with a lock it does not own. `blocking` is `block_in_place` on the multi-threaded
    /// runtime (the server's, see `cpp_ls.rs`) and a plain call in a test's current-thread one.
    pub fn with_snapshot<T>(&self, f: impl FnOnce(&Session<DiskFiles>) -> T) -> Option<T> {
        let session = blocking(move || {
            let session = self.read();
            session.as_ref().map(f)
        })?;
        Some(session)
    }

    /// Logical parallelism used by the analysis blocking pool.
    pub fn analysis_parallelism() -> usize {
        std::thread::available_parallelism()
            .map(|n| n.get())
            .unwrap_or(4)
    }

    /// The provider chain a session is opened over — the same files the live session reads.
    ///
    /// A test's way in: it builds a session with [`Session::with_config`] over *this* chain (no compiler is run) to
    /// assert that a buffer written through one handle is what a session reads through the other. Production code
    /// does not need it, because [`AnalysisState::build_session`] uses the same chain.
    #[cfg(test)]
    pub fn files(&self) -> &SessionFiles<DiskFiles> {
        &self.files
    }

    /// Build a session and restore its sharing cache on the blocking pool, without locking the live session.
    /// The caller validates the workspace epoch, replays open buffers and installs it separately.
    pub async fn build_session(
        &self,
        root: PathBuf,
        filter: WatchFilter,
        config_file: Option<PathBuf>,
    ) -> Option<Session<DiskFiles>> {
        let files = self.files.clone();
        match tokio::task::spawn_blocking(move || {
            let session =
                Session::open_with_config_file(root, files, filter, config_file.as_deref());
            let restored = session.load_the_sharing();
            if restored > 0 {
                log::info!("restored {restored} shared contribution(s) from the last run");
            }
            session
        })
        .await
        {
            Ok(session) => Some(session),
            Err(error) if error.is_panic() => std::panic::resume_unwind(error.into_panic()),
            Err(error) => {
                log::error!("failed to construct a workspace session: {error}");
                None
            }
        }
    }

    pub async fn install_session(&self, session: Session<DiskFiles>) {
        self.update("install the session", move |slot| *slot = Some(session))
            .await;
    }

    /// **Run a read-only query, and report where a slow one spent its time.**
    ///
    /// # The measurement, and why the read path needed one of its own
    ///
    /// [`AnalysisState::update`] has reported the longest it held the analysis since the first round of this work,
    /// and that number bounds what a *write* can be made to wait. It says nothing about a **read**, and the two fail
    /// separately — which is the distinction `crates/cpp_ls/tests/latency.rs` was written around and the one that got
    /// lost for three rounds. A query can be slow for three unrelated reasons and this line tells them apart:
    ///
    /// ```text
    ///   wait permit   every core is already running a query — the analysis pool is saturated
    ///   wait gate     an update is in flight: `AnalysisState::update` takes the gate for writing first
    ///   wait session  a writer holds the session, or one is waiting for it (a `SRWLOCK` queues new readers behind
    ///                 a waiting writer, so this is where the pump's own commit shows up)
    ///   ran           the query's own work — reading the index, parsing the file, resolving the scope
    /// ```
    ///
    /// Measured on the latency fixture, this is what separated "the completion waits for the pump" from "the
    /// completion's own query is slow": with the writes in good order the first five completions after `didOpen`
    /// still took 60–1677 ms, and every millisecond of it was in this function's `ran` — the query's own work over an
    /// index that was still filling.
    pub async fn run_blocking<R, F>(&self, f: F) -> Option<R>
    where
        R: Send + 'static,
        F: FnOnce(&Session<DiskFiles>) -> Option<R> + Send + 'static,
    {
        let started = std::time::Instant::now();
        let permit = self.blocking_permits.clone().acquire_owned().await.ok()?;
        let waited_for_a_permit = started.elapsed().as_millis() as u64;

        let inner = self.inner.clone();
        let gate = self.gate.clone().read_owned().await;
        let waited_for_the_gate = started.elapsed().as_millis() as u64;

        let result = tokio::task::spawn_blocking(move || {
            let _permit = permit;
            let locked = std::time::Instant::now();
            let session = inner
                .read()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            let waited_for_the_session = locked.elapsed().as_millis() as u64;
            // The gate is released before the query runs: it orders an update against the queries already in
            // flight, and holding it for the whole query would make every notification queue behind every read.
            drop(gate);
            let ran = std::time::Instant::now();
            // `?` cannot be used here — the closure answers with the timings as well — so `None` is threaded by hand:
            // "no session has been opened" is the one thing the caller distinguishes, and it is the same answer
            // whether the session was missing or the query declined.
            let answer = session.as_ref().and_then(f);
            (
                waited_for_the_session,
                ran.elapsed().as_millis() as u64,
                answer,
            )
        })
        .await;

        match result {
            Ok((waited_for_the_session, ran, answer)) => {
                let took = started.elapsed().as_millis() as u64;
                if took > QUERY_BUDGET.as_millis() as u64 {
                    log::debug!(
                        "a query took {took} ms — permit {waited_for_a_permit} ms, gate {gate} ms, session \
                         {session} ms, ran {ran} ms",
                        gate = waited_for_the_gate - waited_for_a_permit,
                        session = waited_for_the_session,
                    );
                }
                answer
            }
            Err(err) => {
                if err.is_panic() {
                    std::panic::resume_unwind(err.into_panic());
                }
                None
            }
        }
    }

    pub async fn query_blocking<R, F>(&self, f: F) -> RequestOutcome<R>
    where
        R: Send + 'static,
        F: FnOnce(&Session<DiskFiles>) -> Option<R> + Send + 'static,
    {
        match self.run_blocking(f).await {
            Some(value) => RequestOutcome::Ready(value),
            None => RequestOutcome::Missing,
        }
    }

    /// Prepare a current summary and cooked rendering before a diagnostic query.
    ///
    /// File reads and rendering run without the session lock; short commits validate their captured revision. The
    /// bounded catch-up does not drain unrelated project work. `false` means the file is unreadable, not yet ready,
    /// or its prepared work became stale; callers must not treat it as a clean diagnostic report.
    pub async fn prepare_for_a_diagnostic(&self, path: &std::path::Path) -> bool {
        let to_prepare = path.to_path_buf();

        // **`try_read`, not `with_snapshot`.** A blocking read here would queue this request behind whatever write
        // hold is in flight — which during a cold index is the 195 seconds this whole guard exists to avoid. An
        // unavailable lock means "cannot answer the question yet", which is a `false` that falls through to the
        // path below rather than a wait.
        //
        // **What counts as ready is the reading, not the summary.** It used to require `session.view(…)` as well —
        // a *parse of the file* — and requiring one to decide whether there is work to do is the wrong question on
        // a path whose purpose is to be free when there is none. But the summary alone is the other wrong answer:
        // a file can be **read** and not yet **cooked**, and `Session::diagnostics` answers from the cooked reading —
        // so a pull that treated "read" as "ready" skipped the cook and answered from the coarser raw reading.
        // Measured: `a_pulling_client_gets_a_report_and_not_null` and `an_error_typed_into_an_open_file_is_answered`
        // both failed on an unclosed class (a report with no items is "clean" and wrong) once `didOpen` began
        // reading the file before the handler returned. A cooked reading is the honest test — it is exactly the
        // state in which this function has nothing left to do.
        if let Ok(session) = self.inner.try_read()
            && let Some(session) = session.as_ref()
            && session.index().summary(&to_prepare).is_some()
            && session.index().cooked_declarations(&to_prepare).is_some()
            // **And the view, which is what the checks read.** The edit drops the file's rendering before the analysis
            // applies the edit, so for one pull the summary and the cooked reading are still the old ones and there is
            // no view: `checks_about` then has no tree, every finding disappears, and the client is told the file became
            // clean — the flash this function exists to prevent. Measured: `prepare fast path` followed by
            // `view=false checks=0` on the pull right after `didChange`. `has_rendering` checks the same rendering
            // without parsing it on the async runtime.
            && session.has_rendering(&to_prepare)
        {
            return true;
        }

        let target = to_prepare.clone();
        let queued = self
            .update_session("prepare a file a pull request named", move |session| {
                if session.index().summary(&target).is_some()
                    && session.index().cooked_declarations(&target).is_some()
                    && session.has_rendering(&target)
                {
                    return true;
                }
                if session.load(&target).is_none() {
                    return false;
                }
                if !session.contains_project_file(&target) {
                    session.add_project_files([target.clone()]);
                }
                session.want_refinement(&target);
                session.want_cooked_reading(&target);
                true
            })
            .await
            .unwrap_or(false);
        if !queued {
            return false;
        }
        self.wake();

        // **Where a pull's time goes, stage by stage.** The reader's report is "diagnostics sits on a core", and the
        // answer cannot be read off this function: four of its six stages are `run_blocking` calls whose work happens
        // elsewhere. Each one is timed here, at `debug`, because the log line `a query took … ran …` that already
        // exists only says a call was slow, not which call.
        let stage = std::time::Instant::now();
        let mut sliced = 0usize;
        for _ in 0..PREPARE_INDEX_SLICE {
            let Some(next) = self.next_file_for_catch_up(&to_prepare).await else {
                break;
            };
            self.read_queued_file(&next).await;
            sliced += 1;
        }
        let sliced_for = stage.elapsed();

        let target = to_prepare.clone();
        let ready = self
            .run_blocking(move |session| {
                Some(
                    session.index().summary(&target).is_some()
                        && session.index().cooked_declarations(&target).is_some()
                        && session.has_rendering(&target),
                )
            })
            .await
            .unwrap_or(false);
        if ready {
            log::debug!(
                "pull prepare: {sliced} file(s) in {sliced_for:?}, ready after them in {:?} — no cook",
                stage.elapsed() - sliced_for
            );
            return true;
        }
        let checked_for = stage.elapsed() - sliced_for;

        let target = to_prepare.clone();
        let Some(materials) = self
            .run_blocking(move |session| session.gather_a_cook(&target))
            .await
        else {
            return false;
        };
        let gathered_for = stage.elapsed() - sliced_for - checked_for;
        let Some(rendered) = self.render_cooks(vec![materials]).await.pop() else {
            return false;
        };
        let rendered_for = stage.elapsed() - sliced_for - checked_for - gathered_for;
        let committed = self
            .update_session("commit a diagnostic rendering", move |session| {
                session.commit_a_cooked(rendered).is_some()
            })
            .await
            .unwrap_or(false);
        log::debug!(
            "pull prepare: {sliced} file(s) in {sliced_for:?}, check {checked_for:?}, gather {gathered_for:?}, \
             render {rendered_for:?}, commit {:?} ({committed})",
            stage.elapsed() - sliced_for - checked_for - gathered_for - rendered_for
        );
        committed
    }

    /// Tell the analysis what a path's text is now, or answer `None` when no workspace has been opened.
    ///
    /// The notification worker's entry point: `didOpen`, `didChange`, `didSave`, `didClose` and the client's file
    /// events all reach the session through here, and all of them need it to exist.
    /// `label` names the caller for [`AnalysisState::update`]'s budget warning — see the note there.
    pub async fn update_session<R>(
        &self,
        label: &'static str,
        f: impl FnOnce(&mut Session<DiskFiles>) -> R,
    ) -> Option<R> {
        self.update(label, |slot| slot.as_mut().map(f)).await
    }

    /// Change the analysis — including opening and closing the session itself.
    ///
    /// The closure sees the slot rather than a session because this is the one path that can *create* one
    /// ([`AnalysisState::open`] is written in terms of it); an update that has a session to work on wants
    /// [`AnalysisState::update_session`].
    ///
    /// # Which caller was slow, and why it is a label rather than `#[track_caller]`
    ///
    /// `#[track_caller]` is **a no-op on an `async fn`** — rustc says so in a warning, and the first version of this
    /// did exactly that and reported `analysis_state.rs:308` for every slow update, which is this function rather
    /// than the caller. A label is something a caller has to remember to pass, and that is its whole cost; what it
    /// buys is a name in the warning that says which of a dozen call sites did the work.
    pub async fn update<R>(
        &self,
        label: &'static str,
        f: impl FnOnce(&mut Option<Session<DiskFiles>>) -> R,
    ) -> R {
        let inner = self.inner.clone();
        let gate = self.gate.clone().write_owned().await;
        let held = self.worst_write_hold.clone();
        let run = move || {
            let mut slot = inner
                .write()
                .unwrap_or_else(|poisoned| poisoned.into_inner());
            drop(gate);
            // **The number this server is judged by, taken by the server.**
            //
            // A query waits for whatever this closure does, so the *only* thing that makes this product slow is a
            // closure that takes long — and there is no way to see that from the outside: the request it delayed
            // reports its own total, which also includes the work the request asked for. So every update is timed
            // here, the worst one is kept, and anything over the budget says so with its own number in the log.
            //
            // This is the architecture rather than a diagnostic: [`WRITE_BUDGET`] is the contract, this is what
            // enforces it, and `worst_write_hold` is what a test asserts on. A fix that does not move this number
            // has not fixed anything.
            let started = std::time::Instant::now();
            let answer = f(&mut slot);
            let took = started.elapsed().as_millis() as u64;
            held.fetch_max(took, std::sync::atomic::Ordering::Relaxed);
            if took > WRITE_BUDGET.as_millis() as u64 {
                log::warn!(
                    "`{label}` held the analysis for {took} ms, over the {budget} ms budget — every request in \
                     flight waited for it",
                    budget = WRITE_BUDGET.as_millis()
                );
            }
            answer
        };
        blocking(run)
    }

    /// **The longest any update has held the analysis**, in milliseconds, since this state was created.
    ///
    /// The one number that bounds a request's wait: a query takes the same lock an update does, so no request can be
    /// delayed by more than this. Read by the tests, and worth reading from a log line when a report says a
    /// completion took a second — if this is small and the request was slow, the wait was inside the request's own
    /// work rather than in the queue.
    pub fn worst_write_hold(&self) -> u64 {
        self.worst_write_hold
            .load(std::sync::atomic::Ordering::Relaxed)
    }

    fn read(&self) -> RwLockReadGuard<'_, Option<Session<DiskFiles>>> {
        self.inner
            .read()
            .unwrap_or_else(|poisoned| poisoned.into_inner())
    }
}

/// Run `f` where blocking is allowed: on the server's multi-threaded runtime the thread hands its other tasks on
/// (`block_in_place`), and anywhere else — a test's current-thread runtime — it is called directly, because
/// `block_in_place` panics there.
fn blocking<R>(f: impl FnOnce() -> R) -> R {
    if tokio::runtime::Handle::try_current()
        .map(|handle| handle.runtime_flavor() == tokio::runtime::RuntimeFlavor::MultiThread)
        .unwrap_or(false)
    {
        tokio::task::block_in_place(f)
    } else {
        f()
    }
}

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

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

    /// **Diagnostics for a file nobody has indexed are still an answer.**
    ///
    /// This is the defect as a contract, with no pump and no clock in it. A diagnostic is answered from the file's
    /// **cooked reading**, and an edit drops that reading — so the pass that runs after typing stops would find none
    /// and publish nothing, however long the user waited. Measured on this shape:
    ///
    /// ```text
    /// before the edit:       Some(1)
    /// right after the edit:  None       ← what the client was told, as nothing at all
    /// after re-indexing:     Some(1)
    /// ```
    ///
    /// The file here is a buffer with no summary and nothing having cooked it, which is exactly the state a file is
    /// in between an edit and the index pump reaching it. A handler that only *reads* answers `None` — and that
    /// `None` reached the client as a JSON `null`; one that cooks the file's current text answers, which is what
    /// makes the pull path independent of the pump's queue.
    #[tokio::test]
    async fn diagnostics_are_answered_before_the_index_has_read_the_file() {
        let state = AnalysisState::new();
        let root = std::env::temp_dir().join("cppls-analysis-state-tests");
        opened(&state, &root).await;

        // A missing `;`, which is a parse error and nothing else.
        let buffer = "int g();\nstruct Name {\n    int middleName;\n    void print(int i) {\n        middleName = i\n    }\n};\n";
        state.files().overlay.open("/p/main.cpp", buffer);
        // **Indexed, then edited** — the sequence the defect lives in. A file the client has open is one the index
        // read, so its reading existed; the edit is what drops it, and the pump is what would bring it back (later
        // than the typing, in a project of any size).
        state
            .update_session("a test's index pass", move |session| {
                session.add_project_files([std::path::PathBuf::from("/p/main.cpp")]);
                session.index_everything();
                session.did_open(std::path::Path::new("/p/main.cpp"), buffer);
                session
                    .diagnostics(std::path::Path::new("/p/main.cpp"))
                    .map(|found| found.errors.len())
            })
            .await;
        // **The state the pass runs in.** Not an assertion — it documents the measurement the fix rests on: after an
        // edit the file has no reading, and this is what the client used to be told, as nothing at all.
        let after_the_edit = state
            .with_snapshot(|session| {
                session
                    .diagnostics(std::path::Path::new("/p/main.cpp"))
                    .map(|found| found.errors.len())
            })
            .flatten();
        assert_eq!(
            after_the_edit, None,
            "an edit drops the file's summary, so a pass that only reads has no answer — which is the defect"
        );

        // **The pull path's own two steps**, which is what a `textDocument/diagnostic` request is made of.
        assert!(
            state
                .prepare_for_a_diagnostic(std::path::Path::new("/p/main.cpp"))
                .await,
            "the file can be read and cooked"
        );
        let diagnostics = state
            .with_snapshot(|session| {
                crate::handlers::diagnostic::diagnose_file(
                    session,
                    std::path::Path::new("/p/main.cpp"),
                )
            })
            .flatten()
            .expect("a file whose text the client is holding has an answer")
            .1;
        assert!(
            diagnostics
                .iter()
                .any(|diagnostic| diagnostic.message.contains(';')),
            "the missing `;` is the only thing wrong with the buffer: {:?}",
            diagnostics
                .iter()
                .map(|diagnostic| diagnostic.message.clone())
                .collect::<Vec<_>>()
        );
    }

    /// A workspace with a session the test built itself.
    ///
    /// [`AnalysisState::open`] runs the compiler (`Session::open` asks it for its search paths), which is not
    /// something a unit test should do: the contract under test here is *this* state's — that a session exists
    /// before a query, and that the buffers are shared — and `with_config` gives it one without a toolchain.
    async fn opened(state: &AnalysisState, root: &std::path::Path) {
        let files = state.files().clone();
        let root = root.to_path_buf();
        let opened = state
            .update(
                "a test's session",
                move |slot: &mut Option<Session<DiskFiles>>| {
                    *slot = Some(Session::with_config(
                        &root,
                        files,
                        WatchFilter::new(&root),
                        CompilerConfig::default(),
                    ));
                    slot.is_some()
                },
            )
            .await;
        assert!(opened);
    }

    /// **A second pull for a file already analysed must not re-index the project.**
    ///
    /// This is the defect the guard exists for, measured on a real project from the server's own budget warning:
    ///
    /// ```text
    /// 17:52:25 `prepare a file a pull request named` held the analysis for 195264 ms
    /// 17:53:58   … 3524 ms
    /// 17:54:20   … 2068 ms
    /// 17:54:49   … 7018 ms
    /// ```
    ///
    /// Every one of those is `add_project_files` re-queuing **every file of the project** and `index_everything`
    /// draining it again, for a file whose answer was already sitting in the index. A write hold is what every other
    /// request waits for, so the cost was paid by hover, completion and typing rather than by diagnostics.
    ///
    /// # How the fast path is detected rather than assumed
    ///
    /// Not by timing, which is flaky, and not by the queue, which was measured and does not work: `add_project_files`
    /// refills the index queue and `index_everything` drains it **inside the same write hold**, so a caller outside
    /// that hold sees zero either way. What *is* observable is the thing that made the cost expensive — **taking the
    /// write lock at all**. So the test holds the analysis's own gate for writing and then pulls: a pull that needs
    /// the lock cannot return, and one that finds the work already done answers without it.
    ///
    /// That is also the shape of the defect: the write hold is what every other request waits for, so a pull that
    /// takes it is a pull that delays hover, completion and typing.
    /// **A pull leaves the queue for the pump**, which is the 102 seconds this test exists to prevent.
    ///
    /// `Session::index_everything` loops until the queue is empty, so asking for it asks for the whole project — and
    /// a pull request did. Measured in the server's own log while this was being fixed, with the pump 1 258 files
    /// from finished:
    ///
    /// ```text
    /// 20:24:05 `prepare a file a pull request named` held the analysis for 102700 ms
    /// 20:24:09 index slice: prepared 1, committed 1, write lock held 0 ms, 1 to cook, 0 left
    /// ```
    ///
    /// The assertion is on what the pull **left behind**, because that is the property: a bounded pull hands the
    /// rest of the project back to the loop that owns it. Both directions are covered — this fails if the bound is
    /// removed (zero left), and the cold-start tests next door fail if it is made too small to read a file's
    /// includes.
    #[tokio::test]
    async fn a_pull_leaves_the_queue_for_the_pump() {
        let state = AnalysisState::new();
        let root = std::env::temp_dir().join("cppls-analysis-state-tests");
        opened(&state, &root).await;

        // A project far larger than one pull's slice.
        state
            .files()
            .overlay
            .open("/p/main.cpp", "int main() { return 0; }\n");
        let many: Vec<PathBuf> = (0..1500)
            .map(|at| PathBuf::from(format!("/p/file{at}.cpp")))
            .collect();
        for path in &many {
            state.files().overlay.open(
                path.to_str().unwrap_or_default(),
                "int a_variable_in_this_file = 0;\n",
            );
        }
        state
            .update_session("the fixture's discovery", move |session| {
                session.add_project_files(many);
            })
            .await;

        state
            .prepare_for_a_diagnostic(std::path::Path::new("/p/main.cpp"))
            .await;

        let left = state
            .with_snapshot(|session| session.pending())
            .unwrap_or(usize::MAX);
        assert!(
            left > 0,
            "a pull must not drain the whole project — that was 102 seconds of write hold, and every keystroke, \
             hover and completion in the editor waited for it"
        );
    }

    /// **A second pull for a file already analysed must not re-index the project.**
    ///
    /// This is the defect the guard exists for, measured on a real project from the server's own budget warning:
    ///
    /// ```text
    /// 17:52:25 `prepare a file a pull request named` held the analysis for 195264 ms
    /// 17:53:58   … 3524 ms
    /// 17:54:20   … 2068 ms
    /// 17:54:49   … 7018 ms
    /// ```
    ///
    /// Every one of those is discovery work that had already been done, for a file whose answer was already in the
    /// index. A write hold is what every other request waits for, so the cost was paid by hover, completion and
    /// typing rather than by diagnostics.
    ///
    /// # How the fast path is detected rather than assumed
    ///
    /// Not by timing, which is flaky, and not by the queue, which was measured and does not work: `add_project_files`
    /// refills the index queue and the drain empties it **inside the same write hold**, so a caller outside that hold
    /// sees zero either way. What *is* observable is the thing that made the cost expensive — **taking the write lock
    /// at all**. So the test holds the analysis's own gate for writing and then pulls: a pull that needs the lock
    /// cannot return, and one that finds the work already done answers without it.
    ///
    /// That is also the shape of the defect: the write hold is what every other request waits for, so a pull that
    /// takes it is a pull that delays hover, completion and typing.
    #[tokio::test]
    async fn a_second_pull_does_not_take_the_analysis_for_writing() {
        let state = AnalysisState::new();
        let root = std::env::temp_dir().join("cppls-analysis-state-tests");
        opened(&state, &root).await;

        state
            .files()
            .overlay
            .open("/p/main.cpp", "int main() { return 0; }\n");
        let path = std::path::Path::new("/p/main.cpp");

        // **The first pull does the work**, and it is the file's first: the cold path, unchanged.
        assert!(
            state.prepare_for_a_diagnostic(path).await,
            "the file can be read and cooked"
        );
        state
            .update_session("a test's drain", |session| session.index_everything())
            .await;
        assert!(
            state
                .with_snapshot(|session| session.view(path).is_some())
                .unwrap_or(false),
            "the fixture must reach the analysed state, or this test proves nothing about skipping it"
        );

        // **Hold the gate for writing.** Any `update_session` — which is what the slow path is made of — blocks
        // here, so a pull that returns has proved it never asked for the lock.
        let held = state.gate.clone().write_owned().await;
        let second = tokio::time::timeout(
            std::time::Duration::from_secs(2),
            state.prepare_for_a_diagnostic(path),
        )
        .await;
        drop(held);

        assert_eq!(
            second,
            Ok(true),
            "a file already indexed and cooked is prepared from the read lock alone; a pull that needed the write \
             lock would still be waiting here — and that wait is what every other request pays"
        );
    }

    /// A buffer the client opened is the text the analysis reads, through **both** handles: the state's provider
    /// chain and the session's. This is the property the whole arrangement exists for — a second owner of a chain
    /// that is the same chain, not a copy of it.
    #[tokio::test]
    async fn a_buffer_written_through_the_handle_is_read_by_the_session() {
        let state = AnalysisState::new();
        let root = std::env::temp_dir().join("cppls-analysis-state-tests");
        opened(&state, &root).await;

        let buffer = "int from_the_handle;\n";
        state.files().overlay.open("/p/main.cpp", buffer);
        // The buffer is in the provider chain, but a *session* holds a file only once something has read it — which
        // is what the notification path does for a file the client has open (`AnalysisState::prepare`).
        assert!(state.prepare(std::path::Path::new("/p/main.cpp")).await);

        let text = state
            // **The text the analysis reads, asked of the file table rather than of the rendering.** `Session::view` is a
            // request for the *cooked* reading and answers `None` until that work has run — a different claim ("the
            // rendering is ready") from this test's ("the buffer is the text the session holds"). Measured: the assertion
            // read `None` against `Some("int from_the_handle;\n")`.
            .with_snapshot(|session| {
                session
                    .files()
                    .held("/p/main.cpp")
                    .map(|file| file.text.clone())
            })
            .flatten();
        assert_eq!(text.as_deref(), Some(buffer));
    }

    /// Opening a workspace replaces the analysis, and the buffers are still there afterwards — which is what makes
    /// a reload (`compile_commands.json` rewritten, a folder re-opened) cheap rather than a restart.
    #[tokio::test]
    async fn opening_again_replaces_the_session_and_keeps_the_buffers() {
        let state = AnalysisState::new();
        let root = std::env::temp_dir().join("cppls-analysis-state-tests");
        opened(&state, &root).await;
        state.files().overlay.open("/p/main.cpp", "int first;\n");

        opened(&state, &root).await;
        // The **session** was replaced, so its file table is a new one: the buffer survives in the provider chain
        // (which outlives every session) and is read into the new table by the same step that reads any file.
        assert!(state.prepare(std::path::Path::new("/p/main.cpp")).await);

        let text = state
            // **The text the analysis reads, asked of the file table rather than of the rendering.** `Session::view` is a
            // request for the *cooked* reading and answers `None` until that work has run — a different claim ("the
            // rendering is ready") from this test's ("the buffer is the text the session holds"). Measured: the assertion
            // read `None` against `Some("int from_the_handle;\n")`.
            .with_snapshot(|session| {
                session
                    .files()
                    .held("/p/main.cpp")
                    .map(|file| file.text.clone())
            })
            .flatten();
        assert_eq!(
            text.as_deref(),
            Some("int first;\n"),
            "the buffer is in the provider chain, which outlives the session"
        );
    }

    /// Before a workspace is named every query answers "no analysis", which is `Missing` — not an empty answer.
    #[tokio::test]
    async fn a_query_before_the_workspace_is_opened_is_missing() {
        let state = AnalysisState::new();

        let outcome = state
            .query_blocking(|session| Some(session.root().to_path_buf()))
            .await;
        assert!(matches!(outcome, RequestOutcome::Missing));

        let updated = state.update_session("a test's update", |_| 1).await;
        assert_eq!(updated, None, "and there is nothing to update either");
    }

    /// A query and an update reach the analysis at the same time without deadlocking: the read takes a permit and
    /// the read gate, the update takes the write gate and waits for it, and both finish.
    #[tokio::test]
    async fn blocking_query_and_update_complete() {
        let state = Arc::new(AnalysisState::new());
        let root = std::env::temp_dir().join("cppls-analysis-state-tests");
        opened(&state, &root).await;

        let read_state = state.clone();
        let read = tokio::spawn(async move { read_state.run_blocking(|_| Some(1)).await });
        let write_state = state.clone();
        let write = tokio::spawn(async move { write_state.update("a test's update", |_| 2).await });

        assert_eq!(read.await.unwrap(), Some(1));
        assert_eq!(write.await.unwrap(), 2);
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn cancellation_returns_before_a_running_blocking_query_finishes() {
        use super::super::{CancelSource, snapshot_query};
        use tokio_util::sync::CancellationToken;

        let state = Arc::new(AnalysisState::new());
        let root = std::env::temp_dir().join("cppls-analysis-state-tests");
        opened(&state, &root).await;

        let token = CancellationToken::new();
        let (started_tx, started_rx) = tokio::sync::oneshot::channel();
        let (release_tx, release_rx) = std::sync::mpsc::channel();
        let query_state = state.clone();
        let query_token = token.clone();
        let query = tokio::spawn(async move {
            snapshot_query(&query_state, query_token, move |_| {
                started_tx.send(()).unwrap();
                release_rx.recv().unwrap();
                Some(42)
            })
            .await
        });
        tokio::time::timeout(std::time::Duration::from_secs(2), started_rx)
            .await
            .unwrap()
            .unwrap();
        token.cancel();
        let outcome = tokio::time::timeout(std::time::Duration::from_secs(1), query)
            .await
            .unwrap()
            .unwrap();
        assert!(matches!(
            outcome,
            RequestOutcome::Cancelled(CancelSource::Client)
        ));

        let write_state = state.clone();
        let mut write = tokio::spawn(async move { write_state.update("test", |_| 1).await });
        assert!(
            tokio::time::timeout(std::time::Duration::from_millis(50), &mut write)
                .await
                .is_err()
        );
        release_tx.send(()).unwrap();
        assert_eq!(write.await.unwrap(), 1);
    }

    #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
    async fn catching_up_can_be_cancelled_while_waiting_for_the_session_lock() {
        let state = AnalysisState::new();
        let root = std::env::temp_dir().join("cppls-analysis-state-tests");
        opened(&state, &root).await;

        let inner = state.inner.clone();
        let (entered_tx, entered_rx) = tokio::sync::oneshot::channel();
        let (release_tx, release_rx) = std::sync::mpsc::channel();
        let writer = tokio::task::spawn_blocking(move || {
            let _guard = inner.write().unwrap();
            entered_tx.send(()).unwrap();
            let _ = release_rx.recv_timeout(std::time::Duration::from_secs(2));
        });
        entered_rx.await.unwrap();
        let result = tokio::time::timeout(
            std::time::Duration::from_millis(100),
            state.catch_up(&root.join("main.cpp")),
        )
        .await;
        release_tx.send(()).unwrap();
        writer.await.unwrap();
        assert!(
            result.is_err(),
            "waiting for the lock must remain cancellable"
        );
    }
}