lattice_grammar/

source.rs

//! Provenance metadata (DESIGN.md §5.11).
//!
//! Every registered / bound / set thing carries a `SourceLocation`.
//! `:describe-*` formatters render it as a `[[file:...]]`-style link
//! the user can follow to inspect or edit the source.
//!
//! Forgery prevention is structural: there is no public function that
//! takes a `SourceLocation` parameter and stores it. Built-in
//! registrations capture the call site via `#[track_caller]`; static
//! slices use declarative macros (`keymap_entry!`, ...) that inject
//! the location at each row's site. Trusted subsystems (config
//! loader, plugin host bridge, runtime dispatcher) reach the
//! `pub(crate) insert_*` registry methods directly and construct
//! sources from their own ground truth.

use std::path::PathBuf;

/// Where a registered command, binding or option came from: *who* put it
/// there ([`SourceLayer`]) and *where to look* ([`SourceKind`]).
///
/// # Examples
///
/// ```
/// use lattice_grammar::{SourceLayer, SourceLocation};
///
/// let src = SourceLocation::builtin_file("crates/lattice-grammar/src/builtins.rs", 42);
/// assert_eq!(src.layer, SourceLayer::Builtin);
/// assert_eq!(
///     src.as_link(),
///     "[crates/lattice-grammar/src/builtins.rs:42](file:crates/lattice-grammar/src/builtins.rs:42)",
/// );
///
/// // A plugin source renders its manifest name when the caller can resolve it.
/// let p = SourceLocation::plugin(3);
/// assert_eq!(p.as_link(), "[<plugin:3>](synthetic:plugin:3)");
/// assert_eq!(
///     p.as_link_with(&|id| (id == 3).then(|| "comment".to_string())),
///     "[plugin:comment](synthetic:plugin:comment)",
/// );
/// ```
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub struct SourceLocation {
    /// Who contributed the item; rendered as [`SourceLayer::label`].
    pub layer: SourceLayer,
    /// Where the link follower should go.
    pub kind: SourceKind,
}

/// Why this thing exists -- editor binary, user config, plugin, etc.
/// Renders as a one-word label next to the `[[link]]` in help output.
#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum SourceLayer {
    /// Compiled into the editor binary.
    Builtin,
    /// `~/.config/lattice/config.toml`.
    UserConfig,
    /// `.lattice/config.toml` at workspace root.
    ProjectConfig,
    /// Per-buffer modeline / `:setlocal` directive.
    Modeline,
    /// Typed at `:`, replayed by macro, or `.` re-dispatch.
    Runtime,
    /// WASM plugin (Phase 7). The `u32` is the plugin id issued by
    /// the host.
    Plugin(u32),
}

impl SourceLayer {
    /// The one-or-two-word label shown beside the source link in help
    /// output (`"built-in"`, `"user config"`, `"plugin"`, ...). A plugin's
    /// id is not included; see [`SourceLocation::as_link_with`] for naming.
    pub fn label(self) -> &'static str {
        match self {
            SourceLayer::Builtin => "built-in",
            SourceLayer::UserConfig => "user config",
            SourceLayer::ProjectConfig => "project config",
            SourceLayer::Modeline => "modeline",
            SourceLayer::Runtime => "runtime",
            SourceLayer::Plugin(_) => "plugin",
        }
    }
}

/// Where to look. Most cases are a real file with a line; a few are
/// synthetic origins that the link follower routes to a different
/// kind of buffer (command-history, macro buffer, transitive
/// dot-repeat).
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
pub enum SourceKind {
    /// Concrete file location, optionally with a line.
    File {
        /// Path as recorded -- for builtins, the compile-time path from
        /// `Location::caller()` (workspace-relative); for config, the
        /// config file's path.
        path: PathBuf,
        /// 1-based line (as `Location::caller()` reports it); `None` when
        /// only the file is known.
        line: Option<u32>,
    },
    /// `:` invocation. Link follower opens the command-history
    /// buffer at `history_index`.
    CommandLine {
        /// Index into the command-line history.
        history_index: usize,
    },
    /// Replayed from a recorded macro. Link follower opens the
    /// `*macro:<reg>*` buffer at `step`.
    MacroReplay {
        /// The register the macro was recorded into.
        register: char,
        /// Position of the replayed invocation within the macro.
        step: u32,
    },
    /// `.` re-dispatch. Boxes the originating source so chains of
    /// dot-repeats trace back to where the change actually came
    /// from. The link follower follows the inner source.
    DotRepeat(Box<SourceLocation>),
    /// Synthetic origin like `<initial-load>` or `<test-fixture>`.
    /// Renders inert. Owned `String` (not `&'static`) so the type
    /// can derive Deserialize for plugin-bridge wire transport.
    Synthetic(String),
}

impl SourceLocation {
    /// Construct a `Builtin` source from a `(file, line)` pair.
    /// Almost always called via `Location::caller()` in a
    /// `#[track_caller]` registration method.
    pub fn builtin_file(file: &str, line: u32) -> Self {
        Self {
            layer: SourceLayer::Builtin,
            kind: SourceKind::File {
                path: PathBuf::from(file),
                line: Some(line),
            },
        }
    }

    /// Synthetic source for tests + the rare runtime case where no
    /// concrete origin exists.
    pub fn synthetic(tag: impl Into<String>) -> Self {
        Self {
            layer: SourceLayer::Runtime,
            kind: SourceKind::Synthetic(tag.into()),
        }
    }

    /// [`Self::plugin`], with the plugin's manifest name -- which is what a
    /// reader wants. `plugin:comment` answers "where did `gc` come from";
    /// `plugin:1` makes them go and look the number up.
    ///
    /// Separate from [`Self::plugin`] because the name is not always in hand:
    /// `register_plugin_*` runs in the drain with only an id, while a caller
    /// that holds the manifest can do better.
    pub fn plugin_named(plugin_id: u32, name: &str) -> Self {
        Self {
            layer: SourceLayer::Plugin(plugin_id),
            kind: SourceKind::Synthetic(format!("plugin:{name}")),
        }
    }

    /// Provenance for a WASM-plugin contribution (Phase 7). The layer is
    /// [`SourceLayer::Plugin`] carrying the **host-issued** `plugin_id` (§6 —
    /// the guest never supplies it, so a plugin cannot forge a builtin/user
    /// provenance); the kind is a synthetic `plugin:N` tag (a plugin has no
    /// file/line the link follower could open — the plugin-manager view is the
    /// eventual target). This is the *only* forgery-safe way a cross-crate
    /// trusted subsystem stamps `Plugin` provenance: the public
    /// `CommandRegistry::register_plugin_*` methods take a `u32`, never a
    /// `SourceLocation`, and route through here.
    ///
    /// Display sites that can resolve the id to a manifest name do so through
    /// [`Self::as_link_with`]; prefer [`Self::plugin_named`] when the name is
    /// already known.
    pub fn plugin(plugin_id: u32) -> Self {
        Self {
            layer: SourceLayer::Plugin(plugin_id),
            // NOT pre-wrapped in `<>`: `as_link` renders a `Synthetic` tag as
            // `[<tag>](synthetic:tag)`, so a tag that already carries angle
            // brackets shows up as `<<plugin:1>>`.
            kind: SourceKind::Synthetic(format!("plugin:{plugin_id}")),
        }
    }

    /// Render as a markdown link for inclusion in a help body.
    /// Format: `[label](scheme:value)`. The link's URL portion is
    /// what `parse_help_links` (in `lattice-ui-tui::help`)
    /// classifies into a typed `lattice_ui_tui::help::HelpLinkTarget`; the label
    /// is what the user sees.
    pub fn as_link(&self) -> String {
        self.as_link_with(&|_| None)
    }

    /// [`Self::as_link`], with a way to name a plugin.
    ///
    /// The LAYER is authoritative about a source being a plugin's — the
    /// `kind` is only a tag, and one stamped by whichever registration path
    /// happened to run. So the resolver is consulted on `SourceLayer::Plugin`
    /// and its answer wins, which means every display site gets the manifest
    /// name regardless of what was stamped, and `plugin:1` survives only where
    /// the plugin genuinely cannot be named (unloaded, or a harness with no
    /// meta registry).
    pub fn as_link_with(&self, resolve_plugin: &dyn Fn(u32) -> Option<String>) -> String {
        if let SourceLayer::Plugin(pid) = self.layer
            && let Some(name) = resolve_plugin(pid)
        {
            return format!("[plugin:{name}](synthetic:plugin:{name})");
        }
        match &self.kind {
            SourceKind::File {
                path,
                line: Some(n),
            } => {
                let label = escape_link_text(&format!("{}:{}", path.display(), n));
                format!("[{label}](file:{label})")
            }
            SourceKind::File { path, line: None } => {
                let label = escape_link_text(&path.display().to_string());
                format!("[{label}](file:{label})")
            }
            SourceKind::CommandLine { history_index } => {
                format!("[command:{history_index}](history:command:{history_index})")
            }
            SourceKind::MacroReplay { register, step } => {
                format!("[macro:{register}:{step}](macro:{register}:step:{step})")
            }
            SourceKind::DotRepeat(inner) => {
                // The inner source already renders as a markdown link;
                // wrap it as the label of an outer link whose URL is
                // a synthetic dot-repeat-of: scheme. Consumers can
                // peel one level off if they care.
                format!("[dot-repeat-of:{}](dot-repeat-of:inner)", inner.as_link())
            }
            SourceKind::Synthetic(tag) => format!("[<{tag}>](synthetic:{tag})"),
        }
    }
}

/// Backslash-escape the link syntax's own punctuation (`\ [ ] ( )`), as
/// `lattice_help::escape_link_text` does; the help parsers unescape. A
/// Windows path is why: unescaped, `crates\lattice-host\src` lost every
/// separator, in the label and the `file:` URL alike.
fn escape_link_text(text: &str) -> String {
    let mut out = String::with_capacity(text.len());
    for ch in text.chars() {
        if matches!(ch, '\\' | '[' | ']' | '(' | ')') {
            out.push('\\');
        }
        out.push(ch);
    }
    out
}

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

    #[test]
    fn layer_labels_are_human_readable() {
        assert_eq!(SourceLayer::Builtin.label(), "built-in");
        assert_eq!(SourceLayer::UserConfig.label(), "user config");
        assert_eq!(SourceLayer::Plugin(7).label(), "plugin");
    }

    #[test]
    fn builtin_file_renders_as_file_link_with_line() {
        let s = SourceLocation::builtin_file("src/foo.rs", 42);
        assert_eq!(s.as_link(), "[src/foo.rs:42](file:src/foo.rs:42)");
    }

    #[test]
    fn file_link_escapes_backslashes_and_brackets() {
        // A Windows `file!()` path; unescaped, the help parser ate the `\`s.
        let s = SourceLocation::builtin_file(r"crates\x\src\a(b).rs", 3);
        assert_eq!(
            s.as_link(),
            r"[crates\\x\\src\\a\(b\).rs:3](file:crates\\x\\src\\a\(b\).rs:3)"
        );
    }

    #[test]
    fn file_without_line_renders_path_only() {
        let s = SourceLocation {
            layer: SourceLayer::Builtin,
            kind: SourceKind::File {
                path: PathBuf::from("foo.rs"),
                line: None,
            },
        };
        assert_eq!(s.as_link(), "[foo.rs](file:foo.rs)");
    }

    #[test]
    fn command_line_kind_renders_history_link() {
        let s = SourceLocation {
            layer: SourceLayer::Runtime,
            kind: SourceKind::CommandLine { history_index: 3 },
        };
        assert_eq!(s.as_link(), "[command:3](history:command:3)");
    }

    #[test]
    fn macro_replay_kind_renders_macro_link() {
        let s = SourceLocation {
            layer: SourceLayer::Runtime,
            kind: SourceKind::MacroReplay {
                register: 'q',
                step: 5,
            },
        };
        assert_eq!(s.as_link(), "[macro:q:5](macro:q:step:5)");
    }

    /// CM.5: the LAYER decides a source is a plugin's; the resolver names it.
    ///
    /// Keying on the layer rather than the `kind` tag is what makes this
    /// uniform — the tag is whatever the registration path stamped, and the
    /// paths disagree: the chord wiring knows the manifest name while
    /// `register_plugin_operator` holds only an id.
    #[test]
    fn a_plugin_source_renders_its_manifest_name_when_one_resolves() {
        let s = SourceLocation::plugin(7);

        // No resolver: the id, and NOT double-wrapped — `as_link` adds the
        // angle brackets, so a tag carrying its own produced `<<plugin:7>>`.
        assert_eq!(s.as_link(), "[<plugin:7>](synthetic:plugin:7)");

        // With one: the name, whatever the tag says.
        assert_eq!(
            s.as_link_with(&|pid| (pid == 7).then(|| "comment".to_string())),
            "[plugin:comment](synthetic:plugin:comment)"
        );

        // A plugin the host cannot name falls back rather than inventing one.
        assert_eq!(
            s.as_link_with(&|_| None),
            "[<plugin:7>](synthetic:plugin:7)",
            "an unloaded plugin still renders, by id"
        );
    }

    /// A non-plugin source is untouched by the resolver — it must not start
    /// claiming provenance it does not have.
    #[test]
    fn a_builtin_source_ignores_the_plugin_resolver() {
        let s = SourceLocation::builtin_file("src/foo.rs", 42);
        assert_eq!(
            s.as_link_with(&|_| Some("comment".to_string())),
            "[src/foo.rs:42](file:src/foo.rs:42)"
        );
    }

    #[test]
    fn dot_repeat_chains_through_inner_source() {
        let inner = SourceLocation::builtin_file("src/foo.rs", 7);
        let s = SourceLocation {
            layer: SourceLayer::Runtime,
            kind: SourceKind::DotRepeat(Box::new(inner)),
        };
        assert_eq!(
            s.as_link(),
            "[dot-repeat-of:[src/foo.rs:7](file:src/foo.rs:7)](dot-repeat-of:inner)"
        );
    }

    #[test]
    fn synthetic_kind_renders_tagged_link() {
        let s = SourceLocation::synthetic("initial-load");
        assert_eq!(s.as_link(), "[<initial-load>](synthetic:initial-load)");
    }
}