symbolique 0.1.2

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

//! Shared helper and macro for generating symbol writer extension traits.
//!
//! The three symbol pipeline stages (File, Linked, Merged) share identical
//! writer logic — store a shape in `Symbols`, create an index entry in the
//! stage partition. Only the index partition type and method names differ.
//!
//! This module provides:
//! - [`write_shape_and_index`]: generic helper parameterised over the index partition
//! - [`define_symbol_writer!`]: macro that generates a trait + impl for each stage

use {
  crate::{
    core::{Ident, Symbol, SymbolPath, Value, Visibility},
    partitions::{records::SymbolEntry, symbols::Symbols},
  },
  laburnum::database::{
    HasPartition, Partition, PartitionKey, PartitionWriteContextRef, RecordHandle,
    storage::Partitions,
  },
};

/// Store a shape in the shared `Symbols` CAS partition and create an index
/// entry in a stage-specific index partition.
///
/// Also stages a span interval (ADR0007) so that position-based LSP queries
/// can locate the symbol by byte offset.
pub(super) fn write_shape_and_index<P, V, I, Path, S, Idx>(
  writer: &mut PartitionWriteContextRef<'_, P>,
  path: Path,
  span: laburnum::Span,
  shape: Symbol<V, I, Path, S>,
) -> RecordHandle<Symbols<V, I, Path, S>>
where
  P: Partitions,
  V: Value<I> + 'static,
  I: Ident,
  Path: SymbolPath + 'static,
  S: Visibility,
  Idx: Partition<IndexEntry = SymbolEntry<V, I, Path, S>, SortKey = Path>
    + PartitionKey
    + laburnum::database::partitions::SortKeyOf<P>
    + 'static,
  P::Stores: HasPartition<Symbols<V, I, Path, S>> + HasPartition<Idx>,
{
  let handle = writer.store::<Symbols<V, I, Path, S>>(shape);

  let entry = SymbolEntry::new(path.clone(), span, handle);
  writer.index_entry::<Idx>(path.clone(), entry);

  // ADR0007: stage span for position-based lookups. The span entry's sort_key
  // MUST equal the index entry's sort_key string so clears align.
  writer.index_span::<Idx>(path.clone(), span, handle.content_hash());

  handle
}

/// Generate a symbol writer extension trait and its implementation for a
/// pipeline stage.
///
/// # Parameters
///
/// - `trait_name`: Name of the generated trait (e.g. `SymboliqueWriteExt`)
/// - `index_partition`: The index partition type (e.g. `FileSymbols`)
/// - `clear_method`: Name of the clear method (e.g. `clear_file_symbols`)
/// - `method_prefix`: Prefix for write methods — the macro appends
///   `definition`, `reference`, `scope`, `keyword`, `value`, `import`
///
/// # Example
///
/// ```ignore
/// define_symbol_writer! {
///   trait_name: SymboliqueWriteExt,
///   index_partition: FileSymbols,
///   clear_method: clear_file_symbols,
///   method_prefix: write_symbol_,
/// }
/// ```
macro_rules! define_symbol_writer {
  (
    trait_name: $trait_name:ident,
    index_partition: $idx:ident,
    clear_method: $clear:ident,
    method_prefix: $prefix:ident,
  ) => {
    paste::paste! {

    pub trait $trait_name<P: Partitions> {
      fn $clear<V, I, Path, S>(
        &mut self,
        file_prefix: &Path,
      ) where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores: HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >;

      fn [<$prefix definition>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        name: I,
        value: Option<V>,
        visibility: S,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >;

      #[allow(clippy::too_many_arguments)]
      fn [<$prefix reference>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        name: Option<I>,
        target_path: Path,
        is_absolute: bool,
        nameable: bool,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >;

      fn [<$prefix scope>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        value: Option<V>,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >;

      fn [<$prefix keyword>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        name: I,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >;

      fn [<$prefix value>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        value: V,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >;

      fn [<$prefix import>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        import_path: Path,
        alias: Option<I>,
        value: Option<V>,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >;
    }

    impl<P: Partitions> $trait_name<P> for PartitionWriteContextRef<'_, P> {
      fn $clear<V, I, Path, S>(
        &mut self,
        file_prefix: &Path,
      ) where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores: HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >,
      {
        self.clear_prefix::<$idx<V, I, Path, S>>(
          file_prefix.clone(),
        );
      }

      fn [<$prefix definition>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        name: I,
        value: Option<V>,
        visibility: S,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >,
      {
        let shape = Symbol::Definition { name, value, visibility };
        super::symbol_writer_macro::write_shape_and_index::<P, V, I, Path, S, $idx<V, I, Path, S>>(
          self, path, span, shape,
        )
      }

      fn [<$prefix reference>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        name: Option<I>,
        target_path: Path,
        is_absolute: bool,
        nameable: bool,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >,
      {
        let shape = Symbol::Reference { path: path.clone(), name, target_path, is_absolute, nameable };
        super::symbol_writer_macro::write_shape_and_index::<P, V, I, Path, S, $idx<V, I, Path, S>>(
          self, path, span, shape,
        )
      }

      fn [<$prefix scope>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        value: Option<V>,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >,
      {
        let shape = Symbol::Scope { value };
        super::symbol_writer_macro::write_shape_and_index::<P, V, I, Path, S, $idx<V, I, Path, S>>(
          self, path, span, shape,
        )
      }

      fn [<$prefix keyword>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        name: I,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >,
      {
        let shape = Symbol::Keyword { name };
        super::symbol_writer_macro::write_shape_and_index::<P, V, I, Path, S, $idx<V, I, Path, S>>(
          self, path, span, shape,
        )
      }

      fn [<$prefix value>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        value: V,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >,
      {
        let shape = Symbol::Value { value };
        super::symbol_writer_macro::write_shape_and_index::<P, V, I, Path, S, $idx<V, I, Path, S>>(
          self, path, span, shape,
        )
      }

      fn [<$prefix import>]<V, I, Path, S>(
        &mut self,
        path: Path,
        span: laburnum::Span,
        import_path: Path,
        alias: Option<I>,
        value: Option<V>,
      ) -> RecordHandle<Symbols<V, I, Path, S>>
      where
        V: Value<I> + 'static,
        I: Ident,
        Path: SymbolPath + 'static,
        S: Visibility,
        P::Stores:
          HasPartition<Symbols<V, I, Path, S>> + HasPartition<$idx<V, I, Path, S>>,
        $idx<V, I, Path, S>: laburnum::database::partitions::SortKeyOf<P>
          + laburnum::database::Partition<
            SortKey = Path,
            IndexEntry = crate::partitions::records::SymbolEntry<V, I, Path, S>,
          >,
      {
        let shape = Symbol::Import { path: import_path, alias, value };
        super::symbol_writer_macro::write_shape_and_index::<P, V, I, Path, S, $idx<V, I, Path, S>>(
          self, path, span, shape,
        )
      }
    }

    } // paste!
  };
}

pub(super) use define_symbol_writer;