laburnum 1.17.0

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

pub mod source;

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

#[cfg(feature = "test")]
pub use source::TestSourceCacheReader;
pub use source::{
  MaterializedSource, Source, SourceCache, SourceKey, SourceStale, SourceView,
  Span, SpanCache, SpanCacheCheckpoint, SpanData, SpanResolver,
};
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);

pub mod hooks;

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

pub mod database;
pub use database::{
  DynPartition, HasPartition, HasPartitionAt, Partition, PartitionReader,
  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 fs;
pub mod protocol;
pub mod scheduler;
pub mod server;

pub mod uri;
pub use uri::Uri;

pub mod test;

pub mod connect;
pub mod daemon;

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<()>>,
}

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");

    eprintln!("DEBUG: Server::close() - Setting shutdown flag");
    self
      .shutdown_flag
      .store(true, std::sync::atomic::Ordering::SeqCst);

    match self.thread_handle {
      | Some(h) => {
        eprintln!("DEBUG: Server::close() - Waiting for thread to join");
        let result = h.join();
        eprintln!(
          "DEBUG: Server::close() - Thread joined: {:?}",
          result.is_ok()
        );

        result.map(|_| ())
      },
      | None => {
        eprintln!("DEBUG: Server::close() - No thread to join");
        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),
    }
  }

  /// 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();
    let client = connect::lsp::LspClient::new_test(client_conn);

    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 server = Laburnum {
      scheduler: scheduler::Scheduler::new_with_config(
        server_conn,
        self.server,
        filesystems,
        source_cache,
        1,
        self.scheduler_config,
      ),
      io_threads: None,
    }
    .run();

    (server, client)
  }

  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,
}