// Copyright Two Neutron Stars Incorporated and contributors
// SPDX-License-Identifier: BlueOak-1.0.0

//! Laburnum partition-based storage for symbolique.
//!
//! This module implements ADR003's partition-based symbol storage, replacing
//! in-memory SlotMap/HashMap with Laburnum's content-addressed partition
//! system.
//!
//! # Pipeline Stages
//!
//! Symbols flow through 4 stages, each with its own partitions:
//!
//! ```text
//! Stage 1: File     → Symbols (CAS) + FileSymbols (index)
//! Stage 2: Linked   → LinkedSymbols + LinkedSymbolIndex
//! Stage 3: Merged   → MergedSymbols + MergedSymbolIndex
//! Stage 4: Resolved → SymbolResolution (no new shapes)
//! ```
//!
//! # Shapes vs Index
//!
//! Symbol data is split into two partition types:
//!
//! - **[`Symbols`]**: Content-addressed (CAS) partition storing symbol shapes.
//!   Enables deduplication across files. One shared partition for all stages.
//! - **Stage partitions** ([`FileSymbols`], etc.): Index-only partitions with
//!   path-keyed entries. Each entry contains a span and a `RecordHandle` to
//!   the shape in `Symbols`.
//!
//! # Writing Symbols
//!
//! Use the extension traits on `PartitionWriteContextRef`. These are the
//! **only** supported ways to write symbols to partitions:
//!
//! | Stage | Trait | Description |
//! |-------|-------|-------------|
//! | File | [`SymboliqueWriteExt`] | File-level parsing |
//! | Linked | [`LinkedSymboliqueWriteExt`] | Import resolution |
//! | Merged | [`MergedSymboliqueWriteExt`] | Workspace-wide merge |
//! | Resolution | [`ResolutionWriteExt`] | Reference resolution |
//!
//! ```rust,ignore
//! use symbolique::{SymboliqueWriteExt, ResolutionWriteExt};
//!
//! fn build_symbols<P>(writer: &mut PartitionWriteContextRef<'_, P>)
//! where
//!     P: Partitions,
//!     P::Stores: HasPartition<Symbols<MyValue, MyIdent, String>>
//!              + HasPartition<FileSymbols<MyValue, MyIdent, String>>,
//! {
//!     // Clear old symbols before re-parsing
//!     writer.clear_file_symbols::<MyValue, MyIdent, String>(&file_prefix);
//!
//!     // Write symbols - each method stores a shape and creates an index entry
//!     let handle = writer.write_symbol_definition::<MyValue, MyIdent, String>(
//!         path,
//!         span,
//!         name,
//!         Some(value),
//!         SymbolVisibility::Public,
//!     );
//!
//!     // The returned RecordHandle can be stored in LSP records for linking
//! }
//! ```

pub mod file;
pub mod linked;
pub mod merged;
pub mod readers;
pub mod records;
pub mod resolution;
pub mod symbols;
pub mod writers;

// Re-export commonly used types
#[cfg(test)]
pub(crate) mod test_support;

pub use {
  file::{FileSymbolIndex, FileSymbols},
  linked::{LinkedSymbolIndex, LinkedSymbols},
  merged::{MergedSymbolIndex, MergedSymbols},
  records::{ResolutionEntry, ResolutionTarget, SymbolEntry},
  resolution::SymbolResolution,
  symbols::Symbols,
  readers::{
    LinkedSymboliqueReadExt, MergedSymboliqueReadExt, ResolutionReadExt,
    SymboliqueReadExt,
  },
  writers::{
    LinkedSymboliqueWriteExt, MergedSymboliqueWriteExt, ResolutionWriteExt,
    SymboliqueWriteExt,
  },
};
