lattice_config/

option_decl.rs

// `linkme`'s distributed slices use `link_section` to
// aggregate items at link time. Workspace lints `deny`
// `unsafe_code` (CLAUDE.md), so we opt this module in --
// the safety argument is that linkme is the standard Rust
// solution for cross-crate aggregation, the link-section
// usage is contained to its own machinery, and no raw
// pointer / unchecked-cast code lives here.
#![allow(unsafe_code)]

//! Types-as-keys option declarations (M.2.0).
//!
//! Each option is a unique Rust type implementing [`OptionDecl`].
//! Cross-crate uniqueness of the *type* is enforced by Rust's type
//! system (path-qualified types are unambiguously different);
//! cross-crate uniqueness of the *display name* is enforced at
//! startup via [`linkme`] aggregation -- the registry walks the
//! distributed slice [`OPTION_DECLS`] before user-facing work and
//! panics on a duplicate.
//!
//! Strings appear only at boundaries (cmdline `:set`, TOML, plugin
//! manifests, `:describe-option`). Internal access on the hot path
//! is type-driven (`config.get_typed::<Tabstop>()`).
//!
//! See `docs/dev/architecture/mode-architecture.md` §6.4 for the design rationale
//! (types-as-keys eliminating the cross-crate string-collision
//! risk) and §6.8 for the constraint enforcement table (which
//! rules land at compile time vs link time vs plugin-load time).
//!
//! ## Coexistence with the legacy `Option<T>` API
//!
//! M.2.0a lands the trait + macros + linkme aggregation alongside
//! the legacy [`crate::Option`] / [`crate::ConfigRegistry::register`]
//! imperative API. Both work. M.2.0b migrates every built-in
//! option from the imperative API to the macro path; M.2.0c
//! removes the public imperative API. Until then, this module is
//! the *new* declaration surface; the legacy module is the
//! existing one.

use std::any::TypeId;

use crate::option_type::OptionType;

/// Compile-time declaration of one option. Each option type is a
/// unique unit struct (typically generated by the [`crate::options!`]
/// macro) implementing this trait.
///
/// Constants on the trait carry the metadata `:set` / TOML /
/// `:describe-option` need; the type itself carries the identity
/// (`TypeId` lookups for hot-path reads). The associated `Value`
/// type's `OptionType` impl carries the parse / format / enumerate
/// machinery already in this crate.
///
/// `'static` bound: option types are zero-sized markers and have
/// no runtime data; the `'static` lets us key registry storage
/// on `TypeId`.
pub trait OptionDecl: 'static {
    /// The runtime value type. `bool`, `i64`, `String`, plus any
    /// domain enum that impls [`OptionType`].
    type Value: OptionType;

    /// Public display name. Boundary-facing only -- `:set <NAME>=…`,
    /// TOML keys, completion candidates, `:describe-option`.
    /// Internal access is type-driven. The macro derives this
    /// from the option's identifier (with namespace prefix when
    /// declared via `mode_options!`); manually-typed `NAME`s are
    /// not supported for built-in options.
    const NAME: &'static str;

    /// Doc string. Shown in `:describe-option`, the `:customize`
    /// form's per-row help, and `:apropos` results.
    const DOC: &'static str;

    /// Customize-visibility flag. `true` (the default) ⇒ option
    /// appears in `:set` autocomplete + the `:customize` group
    /// view. `false` ⇒ plugin / engine-internal state, hidden
    /// from user surfaces. Equivalent of emacs's `defvar` vs
    /// `defcustom`. (See `mode-architecture.md` §6.5.3.)
    const CUSTOMIZABLE: bool = true;

    /// Default value. Returned by a function (rather than a
    /// `const`) so non-const-constructible types like `String`
    /// can be defaults.
    fn default_value() -> Self::Value;

    /// `TypeId` of the declaration type itself. Hot-path key
    /// for the registry's type-driven storage. Default impl
    /// works for every concrete impl.
    fn type_id() -> TypeId
    where
        Self: Sized,
    {
        TypeId::of::<Self>()
    }
}

/// Group binding declared by [`OptionDecl`] declarations. Each
/// option belongs to exactly one [`crate::OptionGroup`] (selected per
/// declaration block in the macro, with optional per-option
/// override). Stored on the metadata record so `:customize <name>`
/// can prefix-match.
///
/// Trait alias rather than a `const` on `OptionDecl` because the
/// group is set by the macro at the call site, not by the option
/// type itself.
pub trait HasGroup {
    /// Group display name (`"editor"`, `"lsp"`, ...). The macro
    /// pulls this from the `group = SomeGroup;` directive at the
    /// declaration block's head.
    const GROUP_NAME: &'static str;
}

// --- linkme distributed slice + metadata record ---

/// Metadata captured at macro expansion for one option. The
/// `register` function pointer is monomorphised at the call
/// site so the registry boot path can register every option
/// without pulling each `<T>` into a generic over the slice.
///
/// `register_fn` returns `()` and inserts the option into the
/// [`crate::ConfigRegistry`] it is handed (via
/// [`crate::ConfigRegistry::register_with_typeid`]);
/// [`crate::ConfigRegistry::init_from_linkme`] calls it once per
/// element of [`OPTION_DECLS`].
///
/// Also the data the browse surfaces read without a registry:
/// `:customize` groups by [`Self::group_name`] and hides entries
/// whose [`Self::customizable`] is `false`.
pub struct OptionDeclMetadata {
    /// The option's [`OptionDecl::NAME`] — its `:set` / TOML key.
    pub name: &'static str,
    /// The option's [`OptionDecl::DOC`].
    pub doc: &'static str,
    /// The option's [`OptionDecl::CUSTOMIZABLE`]; `false` hides it
    /// from `:customize`.
    pub customizable: bool,
    /// The owning group's display name ([`HasGroup::GROUP_NAME`]),
    /// which `:customize <group>` matches against.
    pub group_name: &'static str,
    /// `&'static str` produced by the value type's
    /// [`OptionType::type_label`] -- captured as a function
    /// pointer so the slice element can be a `static` (the
    /// trait method isn't `const`, so calling it directly in
    /// a static initializer fails). Resolved at the registry
    /// boot loop; cheap (one function call per option, once).
    pub type_label: fn() -> &'static str,
    /// Format the type's default value for diagnostic surfaces
    /// (`:describe-option` "default: X"). Captured as a function
    /// pointer so the slice element stays object-safe-shaped.
    pub default_formatted: fn() -> String,
    /// `TypeId::of::<Self>()` for the declaration type.
    /// Same as `<T as OptionDecl>::type_id()` at the macro
    /// call site; pre-computed so the boot loop doesn't pay
    /// the indirection.
    pub type_id: fn() -> TypeId,
    /// Self-registration thunk. Called by the registry's
    /// `init_from_linkme` boot loop with the registry as
    /// argument; the thunk constructs the runtime
    /// [`crate::option::Option<T>`] spec via `Self::build_spec()` and
    /// calls `registry.register_with_typeid`. The `register_fn`
    /// is generated by the [`crate::options!`] macro and
    /// captures the option's type identity at compile time.
    /// Boot panics (with the option's name in the message) if
    /// any registration fails -- duplicate names at startup
    /// are a build-config bug.
    pub register_fn: fn(&crate::ConfigRegistry),
}

impl OptionDeclMetadata {
    /// Construct a metadata record for the given declaration
    /// type. Helper used by the [`crate::options!`] macro's
    /// generated code; not intended for hand-call.
    pub const fn for_decl<D: OptionDecl + HasGroup>(
        type_label: fn() -> &'static str,
        default_formatted: fn() -> String,
        register_fn: fn(&crate::ConfigRegistry),
    ) -> Self {
        Self {
            name: D::NAME,
            doc: D::DOC,
            customizable: D::CUSTOMIZABLE,
            group_name: D::GROUP_NAME,
            type_label,
            default_formatted,
            type_id: TypeId::of::<D>,
            register_fn,
        }
    }
}

/// Distributed slice of every option declared anywhere in the
/// workspace. Each `options!` macro invocation submits a
/// `&'static OptionDeclMetadata` element here; the registry's
/// startup loader walks the slice to register each option and
/// validate cross-crate display-name uniqueness.
#[linkme::distributed_slice]
pub static OPTION_DECLS: [&'static OptionDeclMetadata];

#[cfg(test)]
mod tests {
    #![allow(clippy::unwrap_used, clippy::panic, clippy::assertions_on_constants)]
    use super::*;

    // Test fixture: declare an option manually (without the
    // macro) so we can exercise the trait surface in isolation.
    // M.2.0a's macro generates equivalent code; M.2.0b migrates
    // production sites.
    struct TestTabstop;
    impl OptionDecl for TestTabstop {
        type Value = i64;
        const NAME: &'static str = "test-tabstop";
        const DOC: &'static str = "Test option for OptionDecl trait.";
        fn default_value() -> i64 {
            8
        }
    }
    impl HasGroup for TestTabstop {
        const GROUP_NAME: &'static str = "editor";
    }

    #[test]
    fn trait_constants_round_trip() {
        assert_eq!(TestTabstop::NAME, "test-tabstop");
        assert_eq!(TestTabstop::DOC, "Test option for OptionDecl trait.");
        assert!(TestTabstop::CUSTOMIZABLE);
        assert_eq!(TestTabstop::default_value(), 8);
    }

    #[test]
    fn type_id_is_unique_per_type() {
        struct A;
        impl OptionDecl for A {
            type Value = bool;
            const NAME: &'static str = "a";
            const DOC: &'static str = "";
            fn default_value() -> bool {
                false
            }
        }
        impl HasGroup for A {
            const GROUP_NAME: &'static str = "editor";
        }
        struct B;
        impl OptionDecl for B {
            type Value = bool;
            const NAME: &'static str = "b";
            const DOC: &'static str = "";
            fn default_value() -> bool {
                false
            }
        }
        impl HasGroup for B {
            const GROUP_NAME: &'static str = "editor";
        }
        assert_ne!(A::type_id(), B::type_id());
        assert_eq!(A::type_id(), TypeId::of::<A>());
    }

    #[test]
    fn metadata_for_decl_carries_constants() {
        fn tl() -> &'static str {
            "integer"
        }
        fn df() -> String {
            "8".to_string()
        }
        fn rf(_r: &crate::ConfigRegistry) {}
        let m = OptionDeclMetadata::for_decl::<TestTabstop>(tl, df, rf);
        assert_eq!(m.name, "test-tabstop");
        assert_eq!(m.group_name, "editor");
        assert_eq!((m.type_label)(), "integer");
        assert_eq!((m.default_formatted)(), "8");
        assert_eq!((m.type_id)(), TypeId::of::<TestTabstop>());
    }
}