lattice_plugin_api/

render.rs

//! PI.6 / AD.1: rendering the plugin-API catalog for humans.
//!
//! Moved out of the host at PI.6. It renders the CATALOG, which is this
//! crate's, and the move is what lets the site's reference page be generated
//! by a test here rather than only by `:export-plugin-api` in a running
//! editor.
//!
//! AD.1 extends every seam from a list of function names to its full surface:
//! signatures, resources and their methods, and every type with its fields or
//! cases. The same [`seam`] renderer backs the single-document form
//! ([`markdown`]) and, from AD.2, one page per seam — so the two cannot
//! disagree about what a seam contains.

use crate::examples::{ApiExample, Examples};
use crate::{
    ApiFunction, ApiFunctionKind, ApiInterface, ApiType, ApiTypeKind, Capability, Direction,
    PluginApiCatalog,
};

/// A seam's [`Direction`] as a phrase for prose: "guest implements this
/// interface". Used by the reference pages and `:describe-plugin-api`.
pub fn direction_prose(d: Direction) -> &'static str {
    match d {
        Direction::GuestExport => "guest implements this interface",
        Direction::GuestImport => "guest calls into the host through it",
        Direction::Both => "guest both implements and calls it",
        Direction::TypesOnly => "shared types only (not called directly)",
    }
}

/// A seam's [`Direction`] as one word for a table cell: `exports`, `imports`,
/// `both`, `types`.
pub fn direction_short(d: Direction) -> &'static str {
    match d {
        Direction::GuestExport => "exports",
        Direction::GuestImport => "imports",
        Direction::Both => "both",
        Direction::TypesOnly => "types",
    }
}

/// A seam's [`Capability`] as a phrase for prose: `filesystem`, `network`, …
pub fn capability_prose(c: Capability) -> &'static str {
    match c {
        Capability::Fs => "filesystem",
        Capability::Net => "network",
        Capability::Proc => "subprocess",
        Capability::None => "none (pure data / dispatch)",
    }
}

/// A seam's [`Capability`] as one token for a table cell: `fs`, `net`,
/// `proc`, or `-` for none.
pub fn capability_short(c: Capability) -> &'static str {
    match c {
        Capability::Fs => "fs",
        Capability::Net => "net",
        Capability::Proc => "proc",
        Capability::None => "-",
    }
}

/// PI.6: the whole plugin API as markdown, rendered from the canonical `wit/`
/// package.
///
/// Lives here rather than in the host because it is a rendering of the
/// CATALOG, and the catalog is this crate's. That placement is what lets the
/// site's reference page be generated by a test in this crate instead of only
/// by `:export-plugin-api` inside a running editor — a reference a developer
/// can only obtain by launching the editor is one they will not read.
pub fn markdown() -> String {
    let cat = crate::catalog();
    let mut out = String::new();
    out.push_str("# Lattice Plugin API\n\n");
    out.push_str(&format!(
        "Derived from the canonical `wit/` package — {} seam(s).\n",
        cat.interfaces.len()
    ));
    for iface in &cat.interfaces {
        out.push('\n');
        out.push_str(&seam(cat, iface, 2));
    }
    out.push('\n');
    out.push_str(&worlds_page(cat, 2));
    out
}

/// The first line of every generated file. Says what generated it and how
/// to regenerate it, so nobody hand-edits a file the next test run reverts.
pub const GENERATED_HEADER: &str = "\
<!-- @generated from wit/ by crates/lattice-plugin-api (render.rs).
     Do not edit: run `UPDATE_SITE_REFERENCE=1 cargo test -p lattice-plugin-api`. -->

";

/// AD.2: the reference as a set of files, relative to `docs/dev/reference/`:
/// the index `plugin-api.md`, one `plugin-api/<seam>.md` per interface, and
/// the machine-readable `plugin-api.json`.
///
/// One page per seam serves both readers: a person lands on the seam they
/// searched for, and an agent loads the one page it needs instead of the
/// whole API.
///
/// `examples` is the scan of the guests ([`crate::examples::scan`]); each one
/// is rendered under the function, type or seam it targets.
pub fn pages(examples: &Examples) -> Vec<(String, String)> {
    let cat = crate::catalog();
    let mut out = vec![(
        "plugin-api.md".to_string(),
        format!("{GENERATED_HEADER}{}", index(cat)),
    )];
    out.push((
        "plugin-api/worlds.md".to_string(),
        format!("{GENERATED_HEADER}{}", worlds_page(cat, 1)),
    ));
    for iface in &cat.interfaces {
        out.push((
            format!("plugin-api/{}.md", iface.name),
            format!(
                "{GENERATED_HEADER}{}",
                seam_with(cat, iface, 1, Links::Pages, Some(examples))
            ),
        ));
    }
    out.push((
        "plugin-api.json".to_string(),
        crate::json::to_json(cat, Some(examples)),
    ));
    out
}

/// The index page: what the API is, how to read it, every world a plugin can
/// target, and every seam with a one-line summary.
fn index(cat: &PluginApiCatalog) -> String {
    let mut out = String::new();
    out.push_str("# Lattice Plugin API\n\n");
    out.push_str(&format!(
        "The plugin API is the WIT package `{}` — {} interfaces (\"seams\") and \
         {} worlds. It is the whole contract: a plugin written in any language \
         with Component-Model tooling (Rust, Go, Zig, JavaScript, …) sees \
         exactly what is on these pages and nothing else. This reference is \
         generated from the `.wit` files in `crates/lattice-wit/wit/`, so it \
         cannot disagree with them.\n\n",
        crate::PACKAGE,
        cat.interfaces.len(),
        cat.worlds.len(),
    ));
    out.push_str(
        "New to writing plugins? Start with the \
         [plugin authoring guide](../../dev/guides/plugin-authoring.md), then \
         come back here for the detail. The same reference in machine-readable \
         form — every seam, signature, type and member — is \
         `docs/dev/reference/plugin-api.json` in the repository and \
         `/plugin-api.json` on the documentation site.\n\n",
    );

    out.push_str("## How to read this reference\n\n");
    out.push_str(
        "- **A plugin targets one world.** The world decides which seams the \
         plugin *exports* (implements — the host calls it) and which it \
         *imports* (calls into the host). In Rust: \
         `wit_bindgen::generate!({ world: \"comment-plugin\", path: \"…/wit\" })`.\n\
         - **Direction** on each seam says which of those it is. A seam marked \
         *shared types only* is never called; other seams `use` its types.\n\
         - **Capability** is what the seam requires of a plugin's grant. Most \
         are `none`: the host does the I/O and hands the guest data.\n\
         - **Resources** (`resource document`) are handles to host-owned state. \
         A `borrow<document>` parameter is valid for that call only.\n\
         - **Errors** are `result<T, string>`: an `err` carries a message the \
         host surfaces to the user, so it should say what went wrong.\n\
         - **WIT to Rust** (wit-bindgen): kebab-case becomes `snake_case` for \
         functions and fields and `UpperCamelCase` for types; `list<T>` is \
         `Vec<T>`, `option<T>` is `Option<T>`, `result<T, E>` is \
         `Result<T, E>`, `borrow<r>` is `&R`.\n\n",
    );

    out.push_str(&format!("## Worlds ({})\n\n", cat.worlds.len()));
    out.push_str(
        "Each world's entry points — the `register-*` functions the host calls \
         on load — are on the [worlds page](plugin-api/worlds.md).\n\n",
    );
    out.push_str("| World | Exports (you implement) | Imports (you may call) |\n");
    out.push_str("|---|---|---|\n");
    for w in &cat.worlds {
        let list = |names: &[String]| {
            if names.is_empty() {
                "—".to_string()
            } else {
                names
                    .iter()
                    .map(|n| format!("[`{n}`](plugin-api/{n}.md)"))
                    .collect::<Vec<_>>()
                    .join(", ")
            }
        };
        let mut exports = list(&w.exports);
        if !w.export_functions.is_empty() {
            let fns = w
                .export_functions
                .iter()
                .map(|f| format!("`{}`", f.name))
                .collect::<Vec<_>>()
                .join(", ");
            exports = if w.exports.is_empty() {
                fns
            } else {
                format!("{exports}; {fns}")
            };
        }
        out.push_str(&format!(
            "| [`{}`](plugin-api/worlds.md#world-{}) | {} | {} |\n",
            w.name,
            w.name,
            exports,
            list(&w.imports)
        ));
    }
    out.push('\n');

    out.push_str(&format!("## Seams ({})\n\n", cat.interfaces.len()));
    out.push_str("| Seam | Direction | Capability | Functions | Types | Summary |\n");
    out.push_str("|---|---|---|---|---|---|\n");
    for i in &cat.interfaces {
        out.push_str(&format!(
            "| [`{}`](plugin-api/{}.md) | {} | {} | {} | {} | {} |\n",
            i.name,
            i.name,
            direction_short(i.direction),
            capability_short(i.capability),
            i.functions.len(),
            i.types.len(),
            summary(i.doc.as_deref()).replace('|', "\\|"),
        ));
    }
    out
}

/// Every world a plugin can target: what it imports and exports, and the
/// freestanding functions it declares — most importantly the entry points the
/// host calls on the guest at load. Those belong to no interface, so this is
/// the only page they appear on.
fn worlds_page(cat: &PluginApiCatalog, level: usize) -> String {
    let h = |n: usize| "#".repeat((level + n).min(6));
    let mut out = format!("{} Worlds\n\n", h(0));
    out.push_str(
        "A plugin component targets exactly one world. The world names the \
         seams the plugin *imports* (host functions it may call) and *exports* \
         (interfaces the host calls on it), plus freestanding functions — above \
         all the `register-*` entry points the host calls once at load, where \
         the plugin declares what it contributes. A plugin that needs seams from \
         two worlds declares its own world that `include`s both.\n",
    );
    let links = |names: &[String]| {
        if names.is_empty() {
            "—".to_string()
        } else {
            names
                .iter()
                .map(|n| format!("[`{n}`]({n}.md)"))
                .collect::<Vec<_>>()
                .join(", ")
        }
    };
    for w in &cat.worlds {
        out.push_str(&format!("\n{} world `{}`\n\n", h(1), w.name));
        if let Some(doc) = &w.doc {
            out.push_str(&demote_headings(doc, level + 2));
            out.push_str("\n\n");
        }
        out.push_str(&format!(
            "**Imports:** {}  \n**Exports:** {}\n\n",
            links(&w.imports),
            links(&w.exports)
        ));
        for (label, fns) in [
            ("Entry points it exports", &w.export_functions),
            ("Functions it imports", &w.import_functions),
        ] {
            if fns.is_empty() {
                continue;
            }
            out.push_str(&format!("**{label}**\n\n"));
            for f in fns {
                function(&mut out, f, &h(2));
            }
        }
    }
    out
}

/// The first sentence of a doc's first paragraph, on one line.
pub fn summary(doc: Option<&str>) -> String {
    let Some(doc) = doc else {
        return String::new();
    };
    let para = doc
        .split("\n\n")
        .next()
        .unwrap_or("")
        .lines()
        .map(str::trim)
        .collect::<Vec<_>>()
        .join(" ");
    match para.find(". ") {
        Some(end) => para[..=end].to_string(),
        None => para,
    }
}

/// One seam's full reference, its title at heading level `level` (1 for a
/// page of its own, 2 inside the single document).
///
/// Order: what it is (direction, capability, worlds), its prose, the types it
/// borrows, its functions, its resources with their methods, then the types it
/// defines in WIT source order. Functions come before types because a reader
/// arrives asking "what can I call"; the types answer the follow-up question.
pub fn seam(cat: &PluginApiCatalog, iface: &ApiInterface, level: usize) -> String {
    seam_with(cat, iface, level, Links::None, None)
}

/// Whether type names become links. The single document is read as one
/// stream (the editor's export buffer, the agent bundle), where a link to a
/// sibling file goes nowhere; the per-seam pages link across files.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Links {
    None,
    /// Per-seam pages that sit side by side: `<seam>.md#<anchor>`.
    Pages,
}

fn seam_with(
    cat: &PluginApiCatalog,
    iface: &ApiInterface,
    level: usize,
    links: Links,
    examples: Option<&Examples>,
) -> String {
    // Examples for `<seam>` or `<seam>.<item>`; none when rendering without
    // a scan (the editor's in-app export — see `examples.rs` for why).
    let examples_for = |item: Option<&str>| -> Vec<&ApiExample> {
        let target = match item {
            Some(item) => format!("{}.{item}", iface.name),
            None => iface.name.clone(),
        };
        examples
            .map(|ex| ex.for_target(&target))
            .unwrap_or_default()
    };
    let h = |n: usize| "#".repeat((level + n).min(6));
    let mut out = String::new();

    out.push_str(&format!("{} `{}`\n\n", h(0), iface.name));
    out.push_str(&format!(
        "**Direction:** {} · **Capability:** {}",
        direction_prose(iface.direction),
        capability_prose(iface.capability),
    ));
    let worlds = worlds_of(cat, &iface.name);
    if !worlds.is_empty() {
        out.push_str(" · **Worlds:** ");
        out.push_str(&worlds.join(", "));
    }
    out.push_str("\n\n");

    if let Some(doc) = &iface.doc {
        out.push_str(&demote_headings(doc, level + 1));
        out.push_str("\n\n");
    }
    example_blocks(&mut out, &examples_for(None), links);

    if !iface.uses.is_empty() {
        out.push_str(&format!("{} Uses\n\n", h(1)));
        for u in &iface.uses {
            let target = type_link(cat, iface, &u.name, links);
            let name = match &target {
                Some(href) => format!("[`{}`]({href})", u.name),
                None => format!("`{}`", u.name),
            };
            let from = match links {
                Links::Pages => format!("[`{}`]({}.md)", u.from, u.from),
                Links::None => format!("`{}`", u.from),
            };
            if u.name == u.original {
                out.push_str(&format!("- {name} from {from}\n"));
            } else {
                out.push_str(&format!("- {name} (`{}` from {from})\n", u.original));
            }
        }
        out.push('\n');
    }

    let freestanding: Vec<&ApiFunction> = iface
        .functions
        .iter()
        .filter(|f| f.kind == ApiFunctionKind::Freestanding)
        .collect();
    let resources: Vec<&ApiType> = iface
        .types
        .iter()
        .filter(|t| t.kind == ApiTypeKind::Resource)
        .collect();

    out.push_str(&format!("{} Functions ({})\n\n", h(1), freestanding.len()));
    if freestanding.is_empty() {
        if resources.is_empty() {
            out.push_str("_(none — a shared type interface)_\n\n");
        } else {
            out.push_str("_(none outside its resources — see Resources below)_\n\n");
        }
    }
    for f in freestanding {
        function(&mut out, f, &h(2));
        example_blocks(&mut out, &examples_for(Some(&f.display_name())), links);
    }

    if !resources.is_empty() {
        out.push_str(&format!("{} Resources\n\n", h(1)));
        for r in resources {
            out.push_str(&format!("{} resource `{}`\n\n", h(2), r.name));
            if let Some(doc) = &r.doc {
                out.push_str(&demote_headings(doc, level + 3));
                out.push_str("\n\n");
            }
            example_blocks(&mut out, &examples_for(Some(&r.name)), links);
            for f in iface.functions.iter().filter(|f| belongs_to(f, &r.name)) {
                function(&mut out, f, &h(3));
                example_blocks(&mut out, &examples_for(Some(&f.display_name())), links);
            }
        }
    }

    let types: Vec<&ApiType> = iface
        .types
        .iter()
        .filter(|t| t.kind != ApiTypeKind::Resource)
        .collect();
    if !types.is_empty() {
        out.push_str(&format!("{} Types ({})\n\n", h(1), types.len()));
        for t in types {
            type_def(&mut out, t, &h(2), level + 3, &|ty| {
                type_link(cat, iface, ty, links)
            });
            example_blocks(&mut out, &examples_for(Some(&t.name)), links);
        }
    }

    out
}

/// The anchor a type's heading gets: `record raw-candidate` →
/// `record-raw-candidate`. Zola and GitHub slug the heading
/// ``record `raw-candidate` `` to the same string, which is what lets one
/// generated link work in both.
pub fn type_anchor(t: &ApiType) -> String {
    format!("{}-{}", t.kind.keyword(), t.name)
}

/// Where the type called `name` in `iface` is defined, as a link, if links are
/// on and `name` is a single named type (a composite like `list<x>` is left as
/// code — it cannot be one link).
fn type_link(
    cat: &PluginApiCatalog,
    iface: &ApiInterface,
    name: &str,
    links: Links,
) -> Option<String> {
    if links == Links::None {
        return None;
    }
    if let Some(t) = iface.types.iter().find(|t| t.name == name) {
        return Some(format!("#{}", type_anchor(t)));
    }
    let u = iface.uses.iter().find(|u| u.name == name)?;
    let def = cat
        .interface(&u.from)?
        .types
        .iter()
        .find(|t| t.name == u.original)?;
    Some(format!("{}.md#{}", u.from, type_anchor(def)))
}

/// Each example: its caption, where it lives, and the code. On the per-seam
/// pages the source path links to the file (the site turns the repo-relative
/// link into a GitHub URL); no line number, because a line number goes stale
/// with every edit above the region and would churn the reference.
fn example_blocks(out: &mut String, examples: &[&ApiExample], links: Links) {
    for e in examples {
        let source = match links {
            Links::Pages => format!("[`{}`](../../../../{})", e.source, e.source),
            Links::None => format!("`{}`", e.source),
        };
        out.push_str(&format!(
            "**Example — {}** · {source}\n\n```rust\n{}\n```\n\n",
            e.caption, e.code
        ));
    }
}

/// A function: heading, WIT signature, full doc.
fn function(out: &mut String, f: &ApiFunction, h: &str) {
    out.push_str(&format!("{h} `{}`\n\n", f.display_name()));
    out.push_str(&format!("```wit\n{}\n```\n\n", f.signature()));
    if let Some(doc) = &f.doc {
        out.push_str(&demote_headings(doc, h.len() + 1));
        out.push_str("\n\n");
    }
}

/// A type: heading, its WIT definition, its doc, then each member's doc.
fn type_def(
    out: &mut String,
    t: &ApiType,
    h: &str,
    doc_level: usize,
    link: &dyn Fn(&str) -> Option<String>,
) {
    out.push_str(&format!("{h} {} `{}`\n\n", t.kind.keyword(), t.name));
    out.push_str(&format!("```wit\n{}\n```\n\n", wit_definition(t)));
    if let Some(doc) = &t.doc {
        out.push_str(&demote_headings(doc, doc_level));
        out.push_str("\n\n");
    }
    // The member list repeats the definition block's names, so it earns its
    // place only by adding something: a member's prose, or a link to a
    // member's type (the code block above cannot link).
    let members = t.kind.members();
    let linked = |m: &crate::ApiMember| m.ty.as_deref().and_then(link);
    if members
        .iter()
        .any(|m| m.doc.is_some() || linked(m).is_some())
    {
        let label = match t.kind {
            ApiTypeKind::Record(_) => "Fields",
            ApiTypeKind::Flags(_) => "Flags",
            _ => "Cases",
        };
        out.push_str(&format!("**{label}**\n\n"));
        for m in members {
            let ty = match (m.ty.as_deref(), linked(m)) {
                (Some(ty), Some(href)) => format!(": [`{ty}`]({href})"),
                (Some(ty), None) => format!(": `{ty}`"),
                (None, _) => String::new(),
            };
            out.push_str(&format!("- `{}`{ty}", m.name));
            match &m.doc {
                Some(doc) => {
                    out.push_str(" — ");
                    out.push_str(&indent_continuation(doc.trim_end(), "  "));
                    out.push('\n');
                }
                None => out.push('\n'),
            }
        }
        out.push('\n');
    }
}

/// The type written back as a WIT declaration, members without docs — the
/// shape at a glance, with the prose below it.
pub fn wit_definition(t: &ApiType) -> String {
    let kw = t.kind.keyword();
    match &t.kind {
        ApiTypeKind::Alias(target) => format!("type {} = {target};", t.name),
        ApiTypeKind::Resource => format!("resource {};", t.name),
        ApiTypeKind::Record(ms)
        | ApiTypeKind::Variant(ms)
        | ApiTypeKind::Enum(ms)
        | ApiTypeKind::Flags(ms) => {
            let is_record = matches!(t.kind, ApiTypeKind::Record(_));
            let mut s = format!("{kw} {} {{\n", t.name);
            for m in ms {
                match (&m.ty, is_record) {
                    (Some(ty), true) => s.push_str(&format!("    {}: {ty},\n", m.name)),
                    (Some(ty), false) => s.push_str(&format!("    {}({ty}),\n", m.name)),
                    (None, _) => s.push_str(&format!("    {},\n", m.name)),
                }
            }
            s.push('}');
            s
        }
    }
}

/// Is `f` a method, static or constructor of the resource `resource`?
fn belongs_to(f: &ApiFunction, resource: &str) -> bool {
    match &f.kind {
        ApiFunctionKind::Freestanding => false,
        ApiFunctionKind::Method(r)
        | ApiFunctionKind::Static(r)
        | ApiFunctionKind::Constructor(r) => r == resource,
    }
}

/// The worlds that import or export `iface`, as `` `world` (exports) ``.
fn worlds_of(cat: &PluginApiCatalog, iface: &str) -> Vec<String> {
    cat.worlds
        .iter()
        .filter_map(|w| {
            let exports = w.exports.iter().any(|e| e == iface);
            let imports = w.imports.iter().any(|i| i == iface);
            match (exports, imports) {
                (true, _) => Some(format!("`{}` (exports)", w.name)),
                (false, true) => Some(format!("`{}` (imports)", w.name)),
                (false, false) => None,
            }
        })
        .collect()
}

/// Push every ATX heading in `doc` down so its top level is `min_level`,
/// leaving fenced code alone. A WIT doc that uses `##` for its own sections
/// must not become a sibling of the seam it describes.
fn demote_headings(doc: &str, min_level: usize) -> String {
    let mut in_fence = false;
    doc.trim_end()
        .lines()
        .map(|line| {
            if line.trim_start().starts_with("```") {
                in_fence = !in_fence;
                return line.to_string();
            }
            if in_fence {
                return line.to_string();
            }
            let hashes = line.chars().take_while(|&c| c == '#').count();
            if hashes > 0 && line[hashes..].starts_with(' ') {
                let level = (hashes + min_level - 1).min(6);
                format!("{}{}", "#".repeat(level), &line[hashes..])
            } else {
                line.to_string()
            }
        })
        .collect::<Vec<_>>()
        .join("\n")
}

/// Indent every line after the first by `pad`, so a multi-line doc stays
/// inside the list item it is attached to.
fn indent_continuation(doc: &str, pad: &str) -> String {
    let mut lines = doc.lines();
    let mut out = lines.next().unwrap_or("").to_string();
    for line in lines {
        out.push('\n');
        if !line.is_empty() {
            out.push_str(pad);
            out.push_str(line);
        }
    }
    out
}