pharos_runtime_docs/

reference.rs

use serde_json::{Map, Value};

const MAX_REFERENCE_TEXT_BYTES: usize = 2 * 1024 * 1024;

/// Performs text.
fn text(value: Option<&Value>) -> String {
    match value {
        Some(Value::String(value)) => value.clone(),
        Some(Value::Null) | None => String::new(),
        Some(value) => serde_json::to_string(value).unwrap_or_default(),
    }
}

/// Performs escape.
fn escape(value: &str) -> String {
    value
        .replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
        .replace('"', "&quot;")
}

/// Returns whether an action declaration has a user-visible effect hook.
///
/// # Parameters
///
/// - `actions`: Input consumed by [`crate::reference::reference_actions_have_effect_hook`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::reference::reference_actions_have_effect_hook`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::reference::reference_actions_have_effect_hook`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_actions_have_effect_hook(todo!());
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_actions_have_effect_hook(actions: &Value) -> bool {
    actions.as_array().is_some_and(|items| {
        items.iter().any(|item| {
            item.get("effect_hook")
                .and_then(Value::as_str)
                .is_some_and(|hook| !hook.is_empty())
        })
    })
}

/// Appends formatted text to a bounded reference buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::reference::reference_buffer_append_format`].
/// - `fragment`: Input consumed by [`crate::reference::reference_buffer_append_format`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::reference::reference_buffer_append_format`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_buffer_append_format(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_buffer_append_format(output: &mut String, fragment: &str) -> bool {
    if output.len().saturating_add(fragment.len()) > MAX_REFERENCE_TEXT_BYTES {
        return false;
    }
    output.push_str(fragment);
    true
}

/// Appends HTML-escaped text to a bounded reference buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::reference::reference_buffer_append_html_escaped`].
/// - `value`: Input consumed by [`crate::reference::reference_buffer_append_html_escaped`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::reference::reference_buffer_append_html_escaped`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_buffer_append_html_escaped(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_buffer_append_html_escaped(output: &mut String, value: &str) -> bool {
    reference_buffer_append_format(output, &escape(value))
}

#[allow(non_snake_case)]
/// Loads one reference fragment template through the current bounded rendering contract.
///
/// # Parameters
///
/// - `template`: Input consumed by [`crate::reference::LOAD_REF_FRAGMENT`].
/// - `parameters`: Input consumed by [`crate::reference::LOAD_REF_FRAGMENT`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::LOAD_REF_FRAGMENT`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::LOAD_REF_FRAGMENT(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn LOAD_REF_FRAGMENT(template: &str, parameters: &Value) -> Option<String> {
    reference_render_fragment(template, parameters)
}

/// Appends one generated reference entry using escaped declarative fields.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::reference::reference_append_generated_entry`].
/// - `entry`: Input consumed by [`crate::reference::reference_append_generated_entry`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::reference::reference_append_generated_entry`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_append_generated_entry(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_append_generated_entry(output: &mut String, entry: &Value) -> bool {
    let name = escape(&text(entry.get("name")));
    let description = escape(&text(entry.get("description")));
    let fragment = format!("<article><h3>{name}</h3><p>{description}</p></article>");
    if output.len().saturating_add(fragment.len()) > MAX_REFERENCE_TEXT_BYTES {
        return false;
    }
    reference_buffer_append_format(output, &fragment)
}

/// Returns a compact sidebar group representation.
///
/// # Parameters
///
/// - `group`: Input consumed by [`crate::reference::reference_sidebar_group`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::reference_sidebar_group`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_sidebar_group(todo!());
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_sidebar_group(group: &Value) -> Option<String> {
    let title = text(group.get("title"));
    let entries = group.get("entries")?.as_array()?;
    (!title.is_empty()).then(|| {
        serde_json::json!({
            "title": title,
            "entries": entries,
        })
        .to_string()
    })
}

/// Returns the escaped sidebar shell text from declarative groups.
///
/// # Parameters
///
/// - `groups`: Input consumed by [`crate::reference::reference_sidebar_shell`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::reference_sidebar_shell`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::reference::reference_sidebar_shell`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_sidebar_shell(todo!());
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_sidebar_shell(groups: &Value) -> Option<String> {
    let groups = groups.as_array()?;
    let mut output = String::from("<aside><nav>");
    for group in groups {
        let title = escape(&text(group.get("title")));
        output.push_str("<section><h2>");
        output.push_str(&title);
        output.push_str("</h2><ul>");
        for entry in group
            .get("entries")
            .and_then(Value::as_array)
            .into_iter()
            .flatten()
        {
            output.push_str("<li>");
            output.push_str(&escape(&text(
                entry.get("label").or_else(|| entry.get("name")),
            )));
            output.push_str("</li>");
        }
        output.push_str("</ul></section>");
    }
    output.push_str("</nav></aside>");
    (output.len() <= MAX_REFERENCE_TEXT_BYTES).then_some(output)
}

/// Renders an escaped reference preview fragment.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::reference::reference_ui_preview_fragment`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::reference_ui_preview_fragment`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_ui_preview_fragment("value");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_ui_preview_fragment(value: &Value) -> Option<String> {
    let title = escape(&text(value.get("title").or_else(|| value.get("name"))));
    let body = escape(&text(
        value.get("body").or_else(|| value.get("description")),
    ));
    Some(format!(
        "<div class=\"reference-preview\"><h3>{title}</h3><p>{body}</p></div>"
    ))
}

/// Appends one reference entry to a bounded output buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::reference::reference_append_reference_entry`].
/// - `entry`: Input consumed by [`crate::reference::reference_append_reference_entry`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::reference::reference_append_reference_entry`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_append_reference_entry(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_append_reference_entry(output: &mut String, entry: &Value) -> bool {
    reference_append_generated_entry(output, entry)
}

/// Converts one reference value into a compact example document.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::reference::reference_example_from_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::reference_example_from_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_example_from_value("value");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_example_from_value(value: &Value) -> Option<String> {
    let example = value
        .get("example")
        .cloned()
        .unwrap_or_else(|| value.clone());
    serde_json::to_string(&example).ok()
}

/// Finds an object by an exact string field.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::reference::reference_find_object_by_string_field`].
/// - `field`: Input consumed by [`crate::reference::reference_find_object_by_string_field`].
/// - `expected`: Input consumed by [`crate::reference::reference_find_object_by_string_field`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::reference_find_object_by_string_field`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::reference::reference_find_object_by_string_field`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_find_object_by_string_field(std::path::Path::new("."), "field", "value");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_find_object_by_string_field<'a>(
    root: &'a Value,
    field: &str,
    expected: &str,
) -> Option<&'a Value> {
    root.as_array()?.iter().find(|item| {
        item.as_object()
            .and_then(|object| object.get(field))
            .and_then(Value::as_str)
            == Some(expected)
    })
}

/// Extracts reference parameters from one object into compact JSON.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::reference::reference_parameters_from_object`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::reference_parameters_from_object`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::reference::reference_parameters_from_object`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_parameters_from_object("value");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_parameters_from_object(value: &Value) -> Option<String> {
    let object = value.as_object()?;
    let mut parameters = Map::new();
    for (key, value) in object {
        if key == "parameters" {
            continue;
        }
        parameters.insert(key.clone(), value.clone());
    }
    serde_json::to_string(&Value::Object(parameters)).ok()
}

/// Appends one object-key parameter to a bounded reference parameter list.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::reference::reference_append_object_key_parameter`].
/// - `key`: Input consumed by [`crate::reference::reference_append_object_key_parameter`].
/// - `value`: Input consumed by [`crate::reference::reference_append_object_key_parameter`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::reference::reference_append_object_key_parameter`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_append_object_key_parameter(todo!(), "key", "value");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_append_object_key_parameter(
    output: &mut Vec<Value>,
    key: &str,
    value: &Value,
) -> bool {
    if key.is_empty() || output.len() >= 4096 {
        return false;
    }
    output.push(serde_json::json!({"key": key, "value": value}));
    true
}

/// Appends one table-of-contents item with an escaped anchor target.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::reference::reference_append_toc_item`].
/// - `label`: Input consumed by [`crate::reference::reference_append_toc_item`].
/// - `anchor`: Input consumed by [`crate::reference::reference_append_toc_item`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::reference::reference_append_toc_item`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_append_toc_item(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_append_toc_item(output: &mut String, label: &str, anchor: &str) -> bool {
    if label.is_empty() || anchor.is_empty() || output.len() >= MAX_REFERENCE_TEXT_BYTES {
        return false;
    }
    output.push_str(&format!(
        "<li><a href=\"#{}\">{}</a></li>",
        escape(anchor),
        escape(label)
    ));
    true
}

/// Returns reference attributes as a compact JSON array.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::reference::reference_attributes_list`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::reference_attributes_list`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_attributes_list("value");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_attributes_list(value: &Value) -> Option<String> {
    let attributes = value.get("attributes").and_then(Value::as_array)?;
    serde_json::to_string(attributes).ok()
}

/// Returns stable pretty JSON for a reference value with a bounded depth/size.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::reference::reference_json_pretty`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::reference_json_pretty`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_json_pretty("value");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_json_pretty(value: &Value) -> Option<String> {
    let text = serde_json::to_string_pretty(value).ok()?;
    (text.len() <= MAX_REFERENCE_TEXT_BYTES).then_some(text)
}

/// Renders a reference fragment from a template value and parameter object.
///
/// # Parameters
///
/// - `template`: Input consumed by [`crate::reference::reference_render_fragment`].
/// - `parameters`: Input consumed by [`crate::reference::reference_render_fragment`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::reference_render_fragment`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::reference::reference_render_fragment`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_render_fragment(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_render_fragment(template: &str, parameters: &Value) -> Option<String> {
    let mut output = template.to_owned();
    for (key, value) in parameters.as_object()? {
        let marker = format!("{{{key}}}");
        output = output.replace(&marker, &escape(&text(Some(value))));
    }
    (output.len() <= MAX_REFERENCE_TEXT_BYTES).then_some(output)
}

/// Summarizes one reference value without exposing uncontrolled nested data.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::reference::reference_value_summary`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::reference::reference_value_summary`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::reference::reference_value_summary`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_value_summary("value");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_value_summary(value: &Value) -> String {
    match value {
        Value::Null => "null".to_owned(),
        Value::Bool(value) => value.to_string(),
        Value::Number(value) => value.to_string(),
        Value::String(value) => value.chars().take(256).collect(),
        Value::Array(values) => format!("array:{}", values.len()),
        Value::Object(values) => format!("object:{}", values.len()),
    }
}

/// Returns the stable JSON type name used by reference rendering.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::reference::reference_value_type_name`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::reference::reference_value_type_name`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::reference_value_type_name("value");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn reference_value_type_name(value: &Value) -> &'static str {
    match value {
        Value::Null => "null",
        Value::Bool(_) => "boolean",
        Value::Number(_) => "number",
        Value::String(_) => "string",
        Value::Array(_) => "array",
        Value::Object(_) => "object",
    }
}

/// Removes the query and fragment from a request target.
///
/// # Parameters
///
/// - `target`: Input consumed by [`crate::reference::request_path_without_query`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::request_path_without_query`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::reference::request_path_without_query`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::request_path_without_query("/");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn request_path_without_query(target: &str) -> Option<String> {
    if target.is_empty() || !target.starts_with('/') {
        return None;
    }
    Some(
        target
            .split(['?', '#'])
            .next()
            .unwrap_or_default()
            .to_owned(),
    )
}

/// Resolves a request target relative to an app mount path.
///
/// # Parameters
///
/// - `mount_path`: Input consumed by [`crate::reference::request_target_for_mount`].
/// - `target`: Input consumed by [`crate::reference::request_target_for_mount`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::reference::request_target_for_mount`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::reference::request_target_for_mount(todo!(), "/");
/// ```
///
/// # Related
///
/// - [`crate::reference`] for adjacent helpers that share the same runtime surface.
pub fn request_target_for_mount(mount_path: &str, target: &str) -> Option<String> {
    let target = request_path_without_query(target)?;
    let mount = if mount_path.is_empty() {
        "/"
    } else {
        mount_path
    };
    if mount == "/" {
        return Some(target);
    }
    let remainder = target.strip_prefix(mount)?;
    Some(if remainder.is_empty() {
        "/".to_owned()
    } else if remainder.starts_with('/') {
        remainder.to_owned()
    } else {
        format!("/{remainder}")
    })
}