laburnum 1.17.3

#![doc = include_str!("../readme.md")]
// Copyright Two Neutron Stars Incorporated and contributors
// SPDX-License-Identifier: BlueOak-1.0.0
#![allow(async_fn_in_trait)]

/// Guides and conceptual documentation, rendered on docs.rs.
#[cfg(doc)]
pub mod docs;

pub mod source;

#[cfg(feature = "chumsky")]
pub use laburnum_syntax_macro::laburnum_syntax;

pub use source::{
  FIRST_UNRESERVED_FILE_ID, FsSegment, FsSegmentKind, KNOWN_IDENTS_FILE_ID,
  LABURNUM_INTERNAL_KNOWN_IDENTS_FILE_ID, MaterializedSource,
  PATH_INTERN_FILE_ID, Source, SourceCache, SourceKey, SourceResolver,
  SourceStale, SourceView, Span, SpanCache, SpanCacheCheckpoint, SpanData,
  UNKNOWN_FILE_ID,
};
#[cfg(feature = "test")]
pub use source::{TestSource, TestSourceCacheReader};
use std::sync::{Arc, atomic::AtomicBool};

/// A value paired with its source span.
///
/// This is the standard way to associate parsed values with their source
/// locations. Use this throughout your AST to enable LSP features like hover,
/// goto definition, etc.
///
/// # Example
/// ```ignore
/// use laburnum::{Ident, Span, Spanned};
///
/// struct FunctionDef {
///   name: Spanned<Ident>,
///   params: Vec<Spanned<Ident>>,
/// }
/// ```
pub type Spanned<T> = (T, Span);

/// An [`Ident`] paired with the source [`Span`] it was parsed from.
///
/// Equality and hashing consider **only** the identifier, never the span: two
/// `SpannedIdent`s carrying the same `Ident` are equal even when parsed from
/// different locations. This lets a `SpannedIdent` stand in for a bare `Ident`
/// as a map key while still carrying the span needed to recover the original
/// source text. Use [`span_eq`](Self::span_eq) for a span-sensitive comparison.
// DO NOT ADD serde::Serialize, serde::Deserialize to this struct
#[derive(Clone, Copy, Debug)]
pub struct SpannedIdent {
  ident: Ident,
  span: Span,
}

impl SpannedIdent {
  /// Pair an identifier with the span it was parsed from.
  pub const fn new(ident: Ident, span: Span) -> Self {
    Self { ident, span }
  }

  /// The inner identifier.
  #[inline]
  pub const fn ident(&self) -> Ident {
    self.ident
  }

  /// The span the identifier was parsed from.
  #[inline]
  pub const fn span(&self) -> Span {
    self.span
  }

  /// Span-sensitive equality: true only when both the identifier **and** its
  /// span match. Plain `==` ignores the span.
  #[inline]
  pub fn span_eq(&self, other: Self) -> bool {
    self.ident == other.ident && self.span == other.span
  }

  /// Construct with an [unknown span](Span::unknown), for tests that only care
  /// about the identifier.
  #[cfg(any(test, feature = "ident_constructor"))]
  pub const fn for_test(ident: Ident) -> Self {
    Self::new(ident, Span::unknown())
  }
}

impl PartialEq for SpannedIdent {
  #[inline]
  fn eq(&self, other: &Self) -> bool {
    self.ident == other.ident
  }
}

impl Eq for SpannedIdent {}

impl PartialOrd for SpannedIdent {
  #[inline]
  fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
    Some(self.cmp(other))
  }
}

impl Ord for SpannedIdent {
  #[inline]
  fn cmp(&self, other: &Self) -> std::cmp::Ordering {
    self.ident.cmp(&other.ident)
  }
}

impl std::hash::Hash for SpannedIdent {
  #[inline]
  fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
    self.ident.hash(state);
  }
}

impl From<Spanned<Ident>> for SpannedIdent {
  #[inline]
  fn from((ident, span): Spanned<Ident>) -> Self {
    Self { ident, span }
  }
}

impl From<SpannedIdent> for Spanned<Ident> {
  #[inline]
  fn from(value: SpannedIdent) -> Self {
    (value.ident, value.span)
  }
}

/// A map keyed by a partition key carried as a [`SpannedIdent`].
///
/// Partition keys always originate from a partition's `PartitionKey::KEY`
/// known-ident const. [`SpannedIdent`] hashes and compares by its identifier
/// alone, so these maps behave identically to keying by the bare `Ident`. They
/// hold one entry per partition (a handful), so the default hasher is fine.
pub type SpannedIdentHashMap<V> = std::collections::HashMap<SpannedIdent, V>;

pub mod hooks;

#[cfg(feature = "chumsky")]
pub mod chumsky;

pub mod database;
pub use database::{
  DynPartition, HasPartition, HasPartitionAt, Partition, PartitionReader,
  PartitionSortKey, PartitionStore, PartitionWriteContextRef, PartitionWriter,
  RecordKey, RecordRef,
  gc::{GarbageCollector, GcPhase, GcPolicy},
  hlist::{HCons, HNil, Here, There},
  query::{
    PartitionQueryBuilder, PartitionWaitingQueryBuilder, QueryClient,
    TypedPartitionQueryBuilder, TypedPartitionWaitingQueryBuilder,
  },
  storage::{
    ContentAddressedStorage, Partitions, PartitionsBuilder, RecordStorage,
  },
};

mod known_idents;

pub mod record;
pub use record::{LaburnumRecord, LaburnumRecordRef, Record};

pub mod diagnostics;
pub mod partitions;
pub mod prelude;
pub mod progress;

pub mod builtin_watchers {
  pub use crate::diagnostics::diagnostic_watcher;
}

pub mod errors;
pub use errors::LaburnumError;

pub mod hash;
pub use hash::{ContentHash, ContentHasher, Ident, IdentHashMap, IdentHashSet};

/// Re-export paste for use by define_partitions! macro.
#[doc(hidden)]
pub use paste;

pub mod exec;
pub mod fs;
pub mod protocol;
pub mod scheduler;
pub mod server;

pub mod uri;
pub use uri::Uri;

#[cfg(feature = "test")]
pub mod test;

pub mod connect;
pub mod daemon;
pub mod verbose;

pub use protocol::jsonrpc::Message;

otel::tracer!();

/// Handle to a running laburnum server.
///
/// The server runs on a dedicated thread, processing LSP messages and executing
/// compilation tasks via the scheduler.
pub struct Server {
  pub shutdown_flag: Arc<AtomicBool>,

  thread_handle: Option<std::thread::JoinHandle<()>>,

  /// In `build_test`, owns the executor the test client's reader and socket
  /// pumps run on, so it drops cleanly when the test drops the `Server`.
  /// `None` for production servers. Held only for its `Drop`.
  #[allow(dead_code)]
  runtime: Option<crate::exec::Runtime>,
}

impl Server {
  #[cfg(feature = "test")]
  /// set shutdown flag true, but dont wait for threads to end
  pub fn close_test(self) -> Option<std::thread::JoinHandle<()>> {
    self
      .shutdown_flag
      .store(true, std::sync::atomic::Ordering::SeqCst);

    self.thread_handle
  }

  /// Waits for the server thread to complete and joins it.
  ///
  /// This blocks until the server shuts down (typically when the LSP client
  /// disconnects).
  pub fn close(self) -> std::thread::Result<()> {
    otel::span!("laburnum.server.close");

    self
      .shutdown_flag
      .store(true, std::sync::atomic::Ordering::SeqCst);

    match self.thread_handle {
      | Some(h) => h.join().map(|_| ()),
      | None => Ok(()),
    }
  }
}

/// Main laburnum instance managing the compilation database and LSP server.
///
/// # Type Parameters
///
/// * `S` - Your [`Partitions`] implementation defining what data the
///   database stores
/// * `T` - Your [`LanguageServer`](protocol::lsp::LanguageServer)
///   implementation handling LSP requests
///
/// # Example
///
/// ```no_run
/// use laburnum::Laburnum;
///
/// # struct MyStorage;
/// # impl laburnum::Partitions for MyStorage {
/// #   type Index = usize;
/// #   type RecordRef<'a> = &'a ();
/// #   type Builder = MyStorageBuilder;
/// #   fn get(&self, _: &Self::Index) -> Option<Self::RecordRef<'_>> { None }
/// #   fn hash_contents(&self, _: &mut laburnum::ContentHasher) {}
/// # }
/// # struct MyStorageBuilder;
/// # impl laburnum::database::storage::PartitionsBuilder for MyStorageBuilder {
/// #   type Storage = MyStorage;
/// #   type Record = ();
/// #   fn push(&mut self, _: Self::Record) -> usize { 0 }
/// #   fn build(self) -> Self::Storage { MyStorage }
/// # }
/// # struct MyServer;
/// # impl laburnum::protocol::lsp::LanguageServer<MyStorage> for MyServer {}
///
/// let server = MyServer;
/// let mut laburnum = Laburnum::<MyStorage, _>::new(server)
///     .build_stdio()
///     .expect("Failed to create server");
///
/// laburnum.run_blocking(); // Runs until client disconnects
/// ```
pub struct Laburnum<
  P: database::storage::Partitions,
  T: protocol::lsp::LanguageServer<P>,
> {
  scheduler: std::sync::Arc<scheduler::Scheduler<P, T>>,

  io_threads: Option<connect::ipc::IoThreads>,
}

impl<P: database::storage::Partitions>
  Laburnum<P, server::LaburnumLanguageServer>
{
  /// Creates a builder with the default
  /// [`LaburnumLanguageServer`](server::LaburnumLanguageServer) implementation.
  ///
  /// The default server provides basic LSP functionality but no
  /// language-specific features. This is mainly useful for testing and
  /// examples.
  pub fn example() -> LaburnumBuilder<P, server::LaburnumLanguageServer> {
    LaburnumBuilder::new(Arc::new(server::LaburnumLanguageServer))
  }
}

impl<P: database::storage::Partitions, T: protocol::lsp::LanguageServer<P>>
  Laburnum<P, T>
where
  T: crate::hooks::LaburnumHooks<P, T>,
{
  /// Creates a new [`LaburnumBuilder`] with your custom language server
  /// implementation.
  ///
  /// # Example
  ///
  /// ```no_run
  /// use laburnum::Laburnum;
  /// # struct MyStorage;
  /// # impl laburnum::Partitions for MyStorage {
  /// #   type Index = usize;
  /// #   type RecordRef<'a> = &'a ();
  /// #   type Builder = MyStorageBuilder;
  /// #   fn get(&self, _: &Self::Index) -> Option<Self::RecordRef<'_>> { None }
  /// #   fn hash_contents(&self, _: &mut laburnum::ContentHasher) {}
  /// # }
  /// # struct MyStorageBuilder;
  /// # impl laburnum::database::storage::PartitionsBuilder for MyStorageBuilder {
  /// #   type Storage = MyStorage;
  /// #   type Record = ();
  /// #   fn push(&mut self, _: Self::Record) -> usize { 0 }
  /// #   fn build(self) -> Self::Storage { MyStorage }
  /// # }
  /// # struct MyServer;
  /// # impl laburnum::protocol::lsp::LanguageServer<MyStorage> for MyServer {}
  ///
  /// let server = MyServer;
  /// let builder = Laburnum::<MyStorage, _>::new(server);
  /// ```
  #[allow(clippy::new_ret_no_self)]
  pub fn new(server: T) -> LaburnumBuilder<P, T> {
    LaburnumBuilder::new(Arc::new(server))
  }

  /// Starts the server on a new thread and returns immediately.
  ///
  /// Returns a [`Server`] handle that can be used to wait for completion.
  /// The server runs until the LSP client disconnects.
  pub fn run(mut self) -> Server {
    let shutdown_flag = self.scheduler.shutdown_flag.clone();

    let thread_handle = otel::span!("laburnum.run", in |cx|{
      std::thread::spawn(move || {
        let _guard = cx.attach();

        self.run_blocking()
      })
    });

    Server {
      shutdown_flag,
      thread_handle: Some(thread_handle),
      runtime: None,
    }
  }

  /// Runs the server on the current thread, blocking until shutdown.
  ///
  /// This processes LSP messages and executes compilation tasks until the
  /// client disconnects. Use [`run`](Self::run) if you want non-blocking
  /// execution.
  pub fn run_blocking(&mut self) {
    self.scheduler.run();
  }

  /// Shuts down the server and wa
  /// its for I/O threads to complete.
  pub fn shutdown(self) -> std::io::Result<()> {
    if let Some(io_threads) = self.io_threads {
      io_threads.join()?;
    }
    Ok(())
  }
}

/// Builder for configuring and creating a [`Laburnum`] instance.
///
/// Allows customization of filesystems and scheduler configuration before
/// building.
pub struct LaburnumBuilder<
  P: database::storage::Partitions,
  T: protocol::lsp::LanguageServer<P>,
> {
  server: Arc<T>,
  filesystems: Vec<crate::fs::FS>,
  scheduler_config: scheduler::SchedulerConfiguration,
  _phantom: std::marker::PhantomData<P>,
}

impl<P: database::storage::Partitions, T: protocol::lsp::LanguageServer<P>>
  LaburnumBuilder<P, T>
{
  /// Creates a new builder with the given language server implementation.
  pub fn new(server: Arc<T>) -> Self {
    Self {
      server,
      filesystems: Vec::new(),
      scheduler_config: scheduler::SchedulerConfiguration::default(),
      _phantom: std::marker::PhantomData,
    }
  }

  /// Adds a filesystem to the server.
  ///
  /// Multiple filesystems can be added. They are queried in order when
  /// resolving file paths.
  pub fn filesystem(mut self, fs: crate::fs::FS) -> Self {
    self.filesystems.push(fs);
    self
  }

  /// Configures the task scheduler.
  ///
  /// Use this to customize worker thread count, GC settings, and other
  /// scheduler behavior.
  ///
  /// # Example
  ///
  /// ```no_run
  /// use laburnum::{Laburnum, scheduler::SchedulerConfiguration};
  /// use std::time::Duration;
  /// # struct MyStorage;
  /// # impl laburnum::Partitions for MyStorage {
  /// #   type Index = usize;
  /// #   type RecordRef<'a> = &'a ();
  /// #   type Builder = MyStorageBuilder;
  /// #   fn get(&self, _: &Self::Index) -> Option<Self::RecordRef<'_>> { None }
  /// #   fn hash_contents(&self, _: &mut laburnum::ContentHasher) {}
  /// # }
  /// # struct MyStorageBuilder;
  /// # impl laburnum::database::storage::PartitionsBuilder for MyStorageBuilder {
  /// #   type Storage = MyStorage;
  /// #   type Record = ();
  /// #   fn push(&mut self, _: Self::Record) -> usize { 0 }
  /// #   fn build(self) -> Self::Storage { MyStorage }
  /// # }
  /// # struct MyServer;
  /// # impl laburnum::protocol::lsp::LanguageServer<MyStorage> for MyServer {}
  ///
  /// let config = SchedulerConfiguration {
  ///     enable_gc: true,
  ///     gc_interval: Duration::from_secs(120),
  ///     ..Default::default()
  /// };
  ///
  /// let server = MyServer;
  /// let laburnum = Laburnum::<MyStorage, _>::new(server)
  ///     .scheduler_config(config)
  ///     .build_stdio()
  ///     .expect("Failed to build");
  /// ```
  pub fn scheduler_config(
    mut self,
    config: scheduler::SchedulerConfiguration,
  ) -> Self {
    self.scheduler_config = config;
    self
  }

  /// Builds a laburnum instance using standard I/O for LSP communication.
  ///
  /// This is the standard way to run an LSP server - reads messages from stdin,
  /// writes responses to stdout. Use this when your language server is launched
  /// by an LSP client (editor).
  ///
  /// # Worker Threads
  ///
  /// Automatically creates `num_cpus - 1` worker threads, leaving one CPU for
  /// the main thread that handles LSP protocol messages.
  ///
  /// # Errors
  ///
  /// Returns an error if stdin/stdout cannot be accessed or if thread creation
  /// fails.
  pub fn build_stdio(self) -> std::io::Result<Laburnum<P, T>> {
    let (connection, io_threads) = connect::ipc::Connection::stdio()?;

    let filesystems =
      std::sync::Arc::new(parking_lot::RwLock::new(self.filesystems));

    let source_cache =
      std::sync::Arc::new(parking_lot::RwLock::new(SourceCache::new()));

    let worker_count = num_cpus::get().saturating_sub(1).max(1);

    Ok(Laburnum {
      scheduler: scheduler::Scheduler::new_with_config(
        connection,
        self.server,
        filesystems,
        source_cache,
        worker_count,
        self.scheduler_config,
      ),
      io_threads: Some(io_threads),
    })
  }

  /// Builds a laburnum instance for testing with in-memory communication.
  ///
  /// Returns both a server handle and an LSP client. Messages are passed via
  /// in-memory channels rather than stdin/stdout, making this suitable for
  /// integration tests.
  ///
  /// # Worker Threads
  ///
  /// Uses a single worker thread for deterministic test behavior.
  ///
  /// # Example
  ///
  /// ```no_run
  /// use laburnum::Laburnum;
  /// # struct MyStorage;
  /// # impl laburnum::Partitions for MyStorage {
  /// #   type Index = usize;
  /// #   type RecordRef<'a> = &'a ();
  /// #   type Builder = MyStorageBuilder;
  /// #   fn get(&self, _: &Self::Index) -> Option<Self::RecordRef<'_>> { None }
  /// #   fn hash_contents(&self, _: &mut laburnum::ContentHasher) {}
  /// # }
  /// # struct MyStorageBuilder;
  /// # impl laburnum::database::storage::PartitionsBuilder for MyStorageBuilder {
  /// #   type Storage = MyStorage;
  /// #   type Record = ();
  /// #   fn push(&mut self, _: Self::Record) -> usize { 0 }
  /// #   fn build(self) -> Self::Storage { MyStorage }
  /// # }
  /// # struct MyServer;
  /// # impl laburnum::protocol::lsp::LanguageServer<MyStorage> for MyServer {}
  ///
  /// let server = MyServer;
  /// let (server_handle, client) = Laburnum::<MyStorage, _>::new(server)
  ///     .build_test();
  ///
  /// // Use client to send LSP requests in tests
  /// ```
  // #[cfg(feature = "test")]
  pub fn build_test(self) -> (Server, connect::lsp::LspClient) {
    let (server_conn, client_conn) = connect::ipc::Connection::memory();

    // The test client's reader runs on a runtime owned by the returned
    // `Server`, so it drops cleanly when the test drops the server.
    let runtime =
      crate::exec::Runtime::new(crate::exec::DEFAULT_CLIENT_IO_THREADS);
    let client =
      connect::lsp::LspClient::new_test(client_conn, runtime.spawner());

    let filesystems =
      std::sync::Arc::new(parking_lot::RwLock::new(self.filesystems));

    let source_cache =
      std::sync::Arc::new(parking_lot::RwLock::new(SourceCache::new()));

    let mut server = Laburnum {
      scheduler: scheduler::Scheduler::new_with_config(
        server_conn,
        self.server,
        filesystems,
        source_cache,
        1,
        self.scheduler_config,
      ),
      io_threads: None,
    }
    .run();
    server.runtime = Some(runtime);

    (server, client)
  }

  /// Builds a single-connection scheduler driven inline by an external async
  /// executor, returning the scheduler directly. The caller spawns
  /// [`Scheduler::run_inline`] on its executor, so the whole server runs on
  /// that executor's thread rather than a dedicated worker pool. Used by the
  /// single-threaded test harness.
  #[cfg(feature = "test")]
  pub fn build_server_inline(
    self,
    server_conn: connect::ipc::Connection,
  ) -> std::sync::Arc<scheduler::Scheduler<P, T>> {
    otel::span!("laburnum.build_server_inline");

    let source_cache =
      std::sync::Arc::new(parking_lot::RwLock::new(SourceCache::new()));

    scheduler::Scheduler::new_inline(
      server_conn,
      self.server,
      std::sync::Arc::new(parking_lot::RwLock::new(self.filesystems)),
      source_cache,
      self.scheduler_config,
    )
  }

  pub fn build_server(self, server_conn: connect::ipc::Connection) -> Server {
    otel::span!("laburnum.build_server");

    let source_cache =
      std::sync::Arc::new(parking_lot::RwLock::new(SourceCache::new()));

    Laburnum {
      scheduler: scheduler::Scheduler::new_with_config(
        server_conn,
        self.server,
        std::sync::Arc::new(parking_lot::RwLock::new(self.filesystems)),
        source_cache,
        1,
        self.scheduler_config,
      ),
      io_threads: None,
    }
    .run()
  }

  pub fn build_daemon(
    self,
    config: daemon::DaemonConfig,
  ) -> daemon::DaemonServer<P, T>
  where
    T: hooks::LaburnumHooks<P, T>,
  {
    otel::span!("laburnum.build_daemon");

    let filesystems =
      std::sync::Arc::new(parking_lot::RwLock::new(self.filesystems));

    let source_cache =
      std::sync::Arc::new(parking_lot::RwLock::new(SourceCache::new()));

    let worker_count = num_cpus::get().saturating_sub(1).max(1);

    daemon::DaemonServer::new(
      self.server.clone(),
      config,
      filesystems,
      source_cache,
      worker_count,
      self.scheduler_config,
    )
  }
}

pub struct TestHarness {
  pub server: Server,
}