Module introspect 

Generic introspection (DESIGN.md §5.11).

Every :describe-* target implements Introspectable; the shared render_introspection function turns one into the help body the host wraps in a HelpBuffer. The trait gives:

• Uniform output: kind + identifier + doc + sources + type-specific extras render in a consistent shape across :describe-command, :describe-key, :describe-option, :describe-event, :describe-mode.
• One place to change: tweaking how sources or extras render touches render_introspection, not every formatter.
• Plug-in for new registries: when typed options (§5.12) / events (§5.10) / modes (Phase 8) land, each adds an impl Introspectable and the introspection surface picks it up automatically.

Examples

use lattice_grammar::{
    HelpSection, Introspectable, SourceEntry, SourceLabel, SourceLocation,
    render_introspection,
};

struct Tabstop(SourceLocation);

impl Introspectable for Tabstop {
    fn kind_label(&self) -> &'static str {
        "option"
    }
    fn identifier(&self) -> String {
        "editor.tabstop".into()
    }
    fn doc(&self) -> &str {
        "Display width of a tab character."
    }
    fn sources(&self) -> Vec<SourceEntry<'_>> {
        vec![SourceEntry { label: SourceLabel::DefinedAt, source: &self.0 }]
    }
    fn extra_sections(&self) -> Vec<HelpSection> {
        vec![HelpSection {
            heading: "Value:".into(),
            lines: vec!["       8".into()],
            anchor: Some("value".into()),
        }]
    }
}

let out = render_introspection(&Tabstop(SourceLocation::builtin_file("config.rs", 12)));
assert_eq!(out.lines[0], "editor.tabstop =");   // identifier + kind icon
assert_eq!(out.lines[2], "Display width of a tab character.");
assert_eq!(out.anchors[0].name, "value");
assert_eq!(out.lines[out.anchors[0].line as usize], "Value:");
assert!(out.lines.last().unwrap().starts_with("Defined at: [config.rs:12]"));

Structs

HelpSection

One named block of body lines. Rendered after the doc and before the source links. Used by impls to surface type-specific structure (e.g. :describe-command renders an “Arguments:” section from args_schema).

RenderedAnchor

Anchor extracted by render_introspection. The line index points at the section’s heading row in the rendered body; a follower scrolls the help buffer to (or near) this row.

RenderedIntrospection

Output of render_introspection. Returns both the rendered lines AND any anchors recorded during rendering. Hosts wrap lines into a HelpBuffer’s content and feed anchors into the HelpBuffer’s anchor index.

SourceEntry

One labeled provenance link in a help body.

Enums

SourceLabel

Human-readable label rendered before the link. Each variant maps to a concrete prose phrase.

Traits

Introspectable

A registered / bound / set thing, queryable from :describe-*.

Functions

render_introspection

Render an Introspectable into help-body lines + anchors. The generic shape every :describe-* produces:

render_introspection_lines

Convenience for callers that only want the rendered lines (no anchor follow-up). Wraps render_introspection and discards anchors.

render_introspection_with

render_introspection, with a plugin-name resolver.