pharos_runtime_docs/

docs.rs

use std::fs;
use std::path::{Path, PathBuf};

use saphyr::LoadableYamlNode;
use serde_json::Value;

/// Performs dbuf put tag open.
///
/// # Parameters
///
/// - `tag_name`: Input consumed by [`crate::docs::dbuf_put_tag_open`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::dbuf_put_tag_open`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::dbuf_put_tag_open(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn dbuf_put_tag_open(tag_name: &str) -> Option<String> {
    (!tag_name.is_empty()).then(|| format!("<{tag_name}>"))
}

/// Performs dbuf put anchor open.
///
/// # Parameters
///
/// - `href`: Input consumed by [`crate::docs::dbuf_put_anchor_open`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::dbuf_put_anchor_open`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::dbuf_put_anchor_open(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn dbuf_put_anchor_open(href: &str) -> Option<String> {
    Some(format!("<a href=\"{}\">", html_escape(href)))
}

/// Performs line len.
///
/// # Parameters
///
/// - `line`: Input consumed by [`crate::docs::line_len`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::docs::line_len`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::line_len(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn line_len(line: &str) -> usize {
    line.len()
}

/// Performs line starts with.
///
/// # Parameters
///
/// - `line`: Input consumed by [`crate::docs::line_starts_with`].
/// - `prefix`: Input consumed by [`crate::docs::line_starts_with`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::line_starts_with`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::line_starts_with(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn line_starts_with(line: &str, prefix: &str) -> bool {
    line.starts_with(prefix)
}

/// Performs skip spaces.
///
/// # Parameters
///
/// - `s`: Input consumed by [`crate::docs::skip_spaces`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::docs::skip_spaces`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::skip_spaces(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn skip_spaces(s: &str) -> &str {
    s.trim_start_matches([' ', '\t'])
}

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

/// Resets a documentation buffer and releases its previous allocation.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::docs::dbuf_init`].
///
/// # Returns
///
/// Returns after [`crate::docs::dbuf_init`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::dbuf_init(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn dbuf_init(output: &mut String) {
    *output = String::new();
}

/// Ensures bounded capacity for one raw buffer append.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::docs::dbuf_ensure`].
/// - `additional`: Input consumed by [`crate::docs::dbuf_ensure`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::dbuf_ensure`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::dbuf_ensure(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn dbuf_ensure(output: &mut String, additional: usize) -> bool {
    let Some(required_len) = output.len().checked_add(additional) else {
        return false;
    };
    if required_len > MAX_DOC_TEXT_BYTES {
        return false;
    }
    output.try_reserve(additional.saturating_add(1)).is_ok()
}

/// Appends one raw buffer fragment within the documentation size limit.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::docs::dbuf_append`].
/// - `value`: Input consumed by [`crate::docs::dbuf_append`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::dbuf_append`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::dbuf_append(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn dbuf_append(output: &mut String, value: &str) -> bool {
    if !dbuf_ensure(output, value.len()) {
        return false;
    }
    output.push_str(value);
    true
}

/// Appends one NUL-terminated C-string equivalent to the buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::docs::dbuf_puts`].
/// - `value`: Input consumed by [`crate::docs::dbuf_puts`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::dbuf_puts`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::dbuf_puts(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn dbuf_puts(output: &mut String, value: &str) -> bool {
    dbuf_append(output, value)
}

/// Transfers the buffer contents, leaving an unallocated empty buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::docs::dbuf_detach`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::dbuf_detach`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::dbuf_detach(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn dbuf_detach(output: &mut String) -> Option<String> {
    (output.capacity() > 0).then(|| std::mem::take(output))
}

/// Performs replace placeholder.
///
/// # Parameters
///
/// - `out`: Input consumed by [`crate::docs::replace_placeholder`].
/// - `template_text`: Input consumed by [`crate::docs::replace_placeholder`].
/// - `placeholder`: Input consumed by [`crate::docs::replace_placeholder`].
/// - `value`: Input consumed by [`crate::docs::replace_placeholder`].
/// - `is_html`: Input consumed by [`crate::docs::replace_placeholder`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::replace_placeholder`] 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::docs::replace_placeholder`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::replace_placeholder(todo!(), todo!(), todo!(), "value", todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn replace_placeholder<'a>(
    out: &mut String,
    template_text: &'a str,
    placeholder: &str,
    value: &str,
    is_html: bool,
) -> Option<&'a str> {
    let mut cursor = 0usize;
    while let Some(relative_open) = template_text[cursor..].find('{') {
        let open = cursor + relative_open;
        let key_start = open + 1;
        let relative_close = template_text[key_start..].find('}')?;
        let close = key_start + relative_close;
        let mut effective_key = &template_text[key_start..close];
        let mut this_is_html = is_html;
        if let Some(stripped) = effective_key.strip_prefix("html:") {
            effective_key = stripped;
            this_is_html = true;
        }
        if effective_key == placeholder {
            out.push_str(&template_text[..open]);
            if this_is_html {
                out.push_str(value);
            } else {
                out.push_str(&html_escape(value));
            }
            return Some(&template_text[close + 1..]);
        }
        cursor = close + 1;
    }
    None
}

/// Converts a bounded YAML scalar value into its canonical text representation.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::docs::docs_yaml_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_yaml_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_yaml_value("value");
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_yaml_value(value: &str) -> Option<String> {
    let trimmed = value.trim();
    if trimmed.is_empty() || trimmed.len() > 64 * 1024 {
        return None;
    }
    Some(trimmed.trim_matches(['\"', '\'']).to_owned())
}

/// Completes one output remap item only when both sides are present.
///
/// # Parameters
///
/// - `source`: Input consumed by [`crate::docs::docs_output_remap_finish_item`].
/// - `output`: Input consumed by [`crate::docs::docs_output_remap_finish_item`].
/// - `) -> Option<(String`: Input consumed by [`crate::docs::docs_output_remap_finish_item`].
/// - `String`: Input consumed by [`crate::docs::docs_output_remap_finish_item`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_output_remap_finish_item`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_output_remap_finish_item(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_output_remap_finish_item(
    source: Option<&str>,
    output: Option<&str>,
) -> Option<(String, String)> {
    let source = source?.trim();
    let output = output?;
    (!source.is_empty()).then(|| (source.to_owned(), output.to_owned()))
}

/// Appends a bounded inline-markup fragment with safe link and code handling.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::docs::append_inline_markup`].
/// - `text`: Input consumed by [`crate::docs::append_inline_markup`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::append_inline_markup`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::docs::append_inline_markup`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::append_inline_markup(todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn append_inline_markup(output: &mut String, text: &str) -> bool {
    if text.len() > 256 * 1024 || output.len().saturating_add(text.len()) > 2 * 1024 * 1024 {
        return false;
    }
    let mut cursor = 0usize;
    while cursor < text.len() {
        let remainder = &text[cursor..];
        if let Some(end) = remainder.find('`') {
            output.push_str(&html_escape(&remainder[..end]));
            let after_open = &remainder[end + 1..];
            let Some(close) = after_open.find('`') else {
                output.push('`');
                output.push_str(&html_escape(after_open));
                return true;
            };
            output.push_str("<code>");
            output.push_str(&html_escape(&after_open[..close]));
            output.push_str("</code>");
            cursor += end + close + 2;
        } else {
            output.push_str(&html_escape(remainder));
            break;
        }
    }
    true
}

#[allow(non_snake_case)]
/// Flushes one markdown paragraph into the output buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::docs::FLUSH_PARA`].
/// - `paragraph`: Input consumed by [`crate::docs::FLUSH_PARA`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::FLUSH_PARA`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::FLUSH_PARA(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn FLUSH_PARA(output: &mut String, paragraph: &str) -> bool {
    if paragraph.trim().is_empty() {
        return true;
    }
    if !append_inline_markup(output, paragraph.trim()) {
        return false;
    }
    output.push_str("\n\n");
    true
}

/// Closes a validated markup tag.
///
/// # Parameters
///
/// - `tag_name`: Input consumed by [`crate::docs::dbuf_put_tag_close`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::dbuf_put_tag_close`] 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::docs::dbuf_put_tag_close`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::dbuf_put_tag_close(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn dbuf_put_tag_close(tag_name: &str) -> Option<String> {
    (!tag_name.is_empty() && tag_name.bytes().all(|byte| byte.is_ascii_alphanumeric()))
        .then(|| format!("</{tag_name}>"))
}

/// Rewrites one documentation link target while rejecting unsafe schemes.
///
/// # Parameters
///
/// - `target`: Input consumed by [`crate::docs::rewrite_link_target`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::rewrite_link_target`] 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::docs::rewrite_link_target`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::rewrite_link_target("/");
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn rewrite_link_target(target: &str) -> Option<String> {
    if target.is_empty() || target.chars().any(char::is_control) {
        return None;
    }
    if target.starts_with("javascript:") || target.starts_with("data:") {
        return None;
    }
    Some(target.to_owned())
}

/// Appends one escaped character to a documentation buffer.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::docs::dbuf_putc`].
/// - `character`: Input consumed by [`crate::docs::dbuf_putc`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::dbuf_putc`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::dbuf_putc(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn dbuf_putc(output: &mut String, character: char) -> bool {
    if character.is_control() && character != '\n' {
        return false;
    }
    let mut encoded = [0u8; 4];
    dbuf_append(output, character.encode_utf8(&mut encoded))
}

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

const MAX_DOC_FILES: usize = 4096;
const MAX_DOC_TEXT_BYTES: usize = 2 * 1024 * 1024;

#[derive(Debug, Clone, Default, Eq, PartialEq)]
/// Public struct `DocsOutputRemap` used by this module.
///
/// # Fields
///
/// - `entries`: Stored field on `DocsOutputRemap`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_docs::docs::DocsOutputRemap>();
/// ```
///
/// # Related
///
/// - [`crate::docs`] for constructors, helpers, and neighboring runtime types.
pub struct DocsOutputRemap {
    pub entries: Vec<(String, String)>,
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Public struct `DocsNavEntry` used by this module.
///
/// # Fields
///
/// - `path`: Stored field on `DocsNavEntry`.
/// - `label`: Stored field on `DocsNavEntry`.
/// - `depth`: Stored field on `DocsNavEntry`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_runtime_docs::docs::DocsNavEntry>();
/// ```
///
/// # Related
///
/// - [`crate::docs`] for constructors, helpers, and neighboring runtime types.
pub struct DocsNavEntry {
    pub path: String,
    pub label: String,
    pub depth: usize,
}

struct DocsNavNode {
    path: String,
    label: String,
    depth: usize,
    children: Vec<DocsNavNode>,
}

/// Performs dbuf free.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::docs::dbuf_free`].
///
/// # Returns
///
/// Returns after [`crate::docs::dbuf_free`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::dbuf_free(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn dbuf_free(output: &mut String) {
    dbuf_init(output);
}

/// Performs docs output remap clear.
///
/// # Parameters
///
/// - `remap`: Input consumed by [`crate::docs::docs_output_remap_clear`].
///
/// # Returns
///
/// Returns after [`crate::docs::docs_output_remap_clear`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_output_remap_clear(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_output_remap_clear(remap: &mut DocsOutputRemap) {
    remap.entries.clear();
}

/// Performs docs output remap append.
///
/// # Parameters
///
/// - `remap`: Input consumed by [`crate::docs::docs_output_remap_append`].
/// - `source`: Input consumed by [`crate::docs::docs_output_remap_append`].
/// - `output`: Input consumed by [`crate::docs::docs_output_remap_append`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::docs_output_remap_append`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_output_remap_append(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_output_remap_append(remap: &mut DocsOutputRemap, source: &str, output: &str) -> bool {
    if source.trim().is_empty() || output.trim().is_empty() || remap.entries.len() >= MAX_DOC_FILES
    {
        return false;
    }
    remap.entries.push((source.to_owned(), output.to_owned()));
    true
}

/// Performs docs output remap lookup source.
///
/// # Parameters
///
/// - `remap`: Input consumed by [`crate::docs::docs_output_remap_lookup_source`].
/// - `source`: Input consumed by [`crate::docs::docs_output_remap_lookup_source`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_output_remap_lookup_source`] 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::docs::docs_output_remap_lookup_source`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_output_remap_lookup_source(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_output_remap_lookup_source<'a>(
    remap: &'a DocsOutputRemap,
    source: &str,
) -> Option<&'a str> {
    remap
        .entries
        .iter()
        .find_map(|(key, value)| (key == source).then_some(value.as_str()))
}

/// Performs docs output remap load JSON array.
///
/// # Parameters
///
/// - `entries`: Input consumed by [`crate::docs::docs_output_remap_load_json_array`].
/// - `remap`: Input consumed by [`crate::docs::docs_output_remap_load_json_array`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::docs::docs_output_remap_load_json_array`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::docs::docs_output_remap_load_json_array`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_output_remap_load_json_array(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_output_remap_load_json_array(entries: &Value, remap: &mut DocsOutputRemap) -> i32 {
    let Some(entries) = entries.as_array() else {
        return 66;
    };
    docs_output_remap_clear(remap);
    for entry in entries {
        let Some(source) = entry.get("source").and_then(Value::as_str) else {
            docs_output_remap_clear(remap);
            return 66;
        };
        let Some(output) = entry.get("output").and_then(Value::as_str) else {
            docs_output_remap_clear(remap);
            return 66;
        };
        if !docs_output_remap_append(remap, source, output) {
            docs_output_remap_clear(remap);
            return 69;
        }
    }
    0
}

/// Performs docs output remap load YAML.
///
/// # Parameters
///
/// - `yaml_text`: Input consumed by [`crate::docs::docs_output_remap_load_yaml`].
/// - `remap`: Input consumed by [`crate::docs::docs_output_remap_load_yaml`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::docs::docs_output_remap_load_yaml`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::docs::docs_output_remap_load_yaml`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_output_remap_load_yaml(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_output_remap_load_yaml(yaml_text: &str, remap: &mut DocsOutputRemap) -> i32 {
    let Ok(documents) = saphyr::Yaml::load_from_str(yaml_text) else {
        return 66;
    };
    let Some(root) = documents.first() else {
        docs_output_remap_clear(remap);
        return 0;
    };
    let Some(items) = root.as_vec() else {
        return 66;
    };
    let values: Vec<Value> = items
        .iter()
        .filter_map(|item| {
            let saphyr::Yaml::Mapping(mapping) = item else {
                return None;
            };
            let source = mapping.iter().find_map(|(key, value)| {
                (key.as_str() == Some("source"))
                    .then(|| value.as_str().map(ToOwned::to_owned))
                    .flatten()
            })?;
            let output = mapping.iter().find_map(|(key, value)| {
                (key.as_str() == Some("output"))
                    .then(|| value.as_str().map(ToOwned::to_owned))
                    .flatten()
            })?;
            Some(serde_json::json!({"source": source, "output": output}))
        })
        .collect();
    docs_output_remap_load_json_array(&Value::Array(values), remap)
}

/// Performs docs default HTML output rel.
fn docs_default_html_output_rel(rel_path: &str) -> Option<String> {
    if rel_path.is_empty() {
        return None;
    }
    let path = Path::new(rel_path);
    let name = path.file_name()?.to_str()?;
    let parent = path.parent().filter(|value| !value.as_os_str().is_empty());
    let output_name = if matches!(name, "README.md" | "index.md") {
        "index.html".to_owned()
    } else if let Some(stem) = name.strip_suffix(".md") {
        format!("{stem}.html")
    } else {
        name.to_owned()
    };
    Some(
        parent
            .map(|value| value.join(&output_name).to_string_lossy().into_owned())
            .unwrap_or(output_name),
    )
}

/// Performs docs output remap lookup default HTML.
///
/// # Parameters
///
/// - `remap`: Input consumed by [`crate::docs::docs_output_remap_lookup_default_html`].
/// - `html_target`: Input consumed by [`crate::docs::docs_output_remap_lookup_default_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_output_remap_lookup_default_html`] 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::docs::docs_output_remap_lookup_default_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_output_remap_lookup_default_html(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_output_remap_lookup_default_html<'a>(
    remap: &'a DocsOutputRemap,
    html_target: &str,
) -> Option<&'a str> {
    remap.entries.iter().find_map(|(source, output)| {
        (docs_default_html_output_rel(source).as_deref() == Some(html_target))
            .then_some(output.as_str())
    })
}

/// Performs docs HTML output rel.
///
/// # Parameters
///
/// - `rel_path`: Input consumed by [`crate::docs::docs_html_output_rel`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_html_output_rel`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_html_output_rel(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_html_output_rel(rel_path: &str) -> Option<String> {
    docs_default_html_output_rel(rel_path)
}

/// Performs docs HTML output rel with remap.
///
/// # Parameters
///
/// - `rel_path`: Input consumed by [`crate::docs::docs_html_output_rel_with_remap`].
/// - `remap`: Input consumed by [`crate::docs::docs_html_output_rel_with_remap`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_html_output_rel_with_remap`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_html_output_rel_with_remap(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_html_output_rel_with_remap(
    rel_path: &str,
    remap: Option<&DocsOutputRemap>,
) -> Option<String> {
    if rel_path.is_empty() {
        return None;
    }
    if rel_path.ends_with(".html") {
        return Some(rel_path.to_owned());
    }
    remap
        .and_then(|value| docs_output_remap_lookup_source(value, rel_path))
        .map(ToOwned::to_owned)
        .or_else(|| docs_default_html_output_rel(rel_path))
}

/// Performs docs page depth.
///
/// # Parameters
///
/// - `page_rel`: Input consumed by [`crate::docs::docs_page_depth`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::docs::docs_page_depth`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::docs::docs_page_depth`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_page_depth(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_page_depth(page_rel: &str) -> usize {
    page_rel.bytes().filter(|byte| *byte == b'/').count()
}

/// Performs docs relative prefix.
///
/// # Parameters
///
/// - `depth`: Input consumed by [`crate::docs::docs_relative_prefix`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_relative_prefix`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_relative_prefix(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_relative_prefix(depth: usize) -> Option<String> {
    (depth <= MAX_DOC_FILES).then(|| "../".repeat(depth))
}

/// Performs docs root href.
///
/// # Parameters
///
/// - `page_rel`: Input consumed by [`crate::docs::docs_root_href`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_root_href`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_root_href(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_root_href(page_rel: &str) -> Option<String> {
    if page_rel.is_empty() {
        return None;
    }
    let depth = docs_page_depth(page_rel);
    if depth == 0 {
        Some("index.html".to_owned())
    } else {
        Some(format!("{}index.html", docs_relative_prefix(depth)?))
    }
}

/// Builds the relative href from output.
fn relative_href_from_output(from_page: &str, target: &str) -> Option<String> {
    let from_dir = from_page
        .rfind('/')
        .map(|index| &from_page[..=index])
        .unwrap_or("");
    let mut common = 0usize;
    let from_bytes = from_dir.as_bytes();
    let target_bytes = target.as_bytes();
    while common < from_bytes.len()
        && common < target_bytes.len()
        && from_bytes[common] == target_bytes[common]
    {
        common += 1;
    }
    while common > 0 && from_dir.as_bytes().get(common - 1) != Some(&b'/') {
        common -= 1;
    }
    let up = from_dir[common..]
        .bytes()
        .filter(|byte| *byte == b'/')
        .count();
    Some(format!(
        "{}{}",
        "../".repeat(up),
        &target[common.min(target.len())..]
    ))
}

/// Resolves docs relative target.
fn resolve_docs_relative_target(page_rel: &str, target: &str) -> Option<String> {
    if page_rel.is_empty() || target.is_empty() {
        return None;
    }
    let page_dir = Path::new(page_rel)
        .parent()
        .unwrap_or_else(|| Path::new(""));
    let candidate = page_dir.join(target);
    let mut segments: Vec<String> = Vec::new();
    for component in candidate.components() {
        match component {
            std::path::Component::CurDir => {}
            std::path::Component::Normal(segment) => {
                segments.push(segment.to_str()?.to_owned());
            }
            std::path::Component::ParentDir => {
                segments.pop()?;
            }
            std::path::Component::RootDir | std::path::Component::Prefix(_) => return None,
        }
    }
    (!segments.is_empty()).then(|| segments.join("/"))
}

#[allow(non_snake_case)]
/// Performs CLOSE LIST.
///
/// # Parameters
///
/// - `output`: Input consumed by [`crate::docs::CLOSE_LIST`].
/// - `ordered`: Input consumed by [`crate::docs::CLOSE_LIST`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::CLOSE_LIST`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::CLOSE_LIST(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn CLOSE_LIST(output: &mut String, ordered: bool) -> bool {
    if ordered {
        dbuf_append(output, "</ol>\n")
    } else {
        dbuf_append(output, "</ul>\n")
    }
}

/// Performs docs markdown to HTML.
///
/// # Parameters
///
/// - `markdown_text`: Input consumed by [`crate::docs::docs_markdown_to_html`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_markdown_to_html`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_markdown_to_html(todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_markdown_to_html(markdown_text: &str) -> Option<String> {
    docs_markdown_to_html_with_remap_for_page(markdown_text, None, "index.html")
}

/// Performs docs markdown to HTML with remap.
///
/// # Parameters
///
/// - `markdown_text`: Input consumed by [`crate::docs::docs_markdown_to_html_with_remap`].
/// - `remap`: Input consumed by [`crate::docs::docs_markdown_to_html_with_remap`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_markdown_to_html_with_remap`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_markdown_to_html_with_remap(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_markdown_to_html_with_remap(
    markdown_text: &str,
    remap: Option<&DocsOutputRemap>,
) -> Option<String> {
    docs_markdown_to_html_with_remap_for_page(markdown_text, remap, "index.html")
}

/// Appends one required docs fragment and converts failure into a render failure.
fn append_docs_text(output: &mut String, value: &str) -> Option<()> {
    dbuf_append(output, value).then_some(())
}

/// Converts the supported Markdown and authored HTML mixture used by Pharos docs.
///
/// # Parameters
///
/// - `markdown_text`: Input consumed by [`crate::docs::docs_markdown_to_html_with_remap_for_page`].
/// - `remap`: Input consumed by [`crate::docs::docs_markdown_to_html_with_remap_for_page`].
/// - `page_rel`: Input consumed by [`crate::docs::docs_markdown_to_html_with_remap_for_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_markdown_to_html_with_remap_for_page`] 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::docs::docs_markdown_to_html_with_remap_for_page`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_markdown_to_html_with_remap_for_page(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_markdown_to_html_with_remap_for_page(
    markdown_text: &str,
    remap: Option<&DocsOutputRemap>,
    page_rel: &str,
) -> Option<String> {
    if markdown_text.len() > MAX_DOC_TEXT_BYTES || page_rel.is_empty() {
        return None;
    }
    let mut output = String::new();
    let mut paragraph = String::new();
    let mut list_kind = None;
    let mut code_fence = None;
    for line in markdown_text.lines() {
        let trimmed = line.trim_end();
        if let Some(language) = trimmed.strip_prefix("```") {
            if code_fence.is_some() {
                append_docs_text(&mut output, "</code></pre>\n")?;
                code_fence = None;
            } else {
                flush_docs_paragraph(&mut output, &mut paragraph, page_rel, remap)?;
                close_docs_list(&mut output, &mut list_kind);
                let language = language.trim();
                if language.len() > 32
                    || !language
                        .bytes()
                        .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'-' | b'_'))
                {
                    return None;
                }
                if language.is_empty() {
                    append_docs_text(&mut output, "<pre><code>")?;
                } else {
                    append_docs_text(
                        &mut output,
                        &format!("<pre><code class=\"language-{language}\">"),
                    )?;
                }
                code_fence = Some(language.to_owned());
            }
            continue;
        }
        if code_fence.is_some() {
            append_docs_text(&mut output, &html_escape(line))?;
            append_docs_text(&mut output, "\n")?;
            continue;
        }
        if let Some((level, title)) = markdown_heading(trimmed) {
            flush_docs_paragraph(&mut output, &mut paragraph, page_rel, remap)?;
            close_docs_list(&mut output, &mut list_kind);
            append_docs_text(&mut output, &format!("<h{level}"))?;
            append_docs_text(&mut output, ">")?;
            append_inline_markup_for_page(&mut output, title, page_rel, remap)?;
            append_docs_text(&mut output, &format!("</h{level}>\n"))?;
            continue;
        }
        if let Some((ordered, item)) = markdown_list_item(trimmed) {
            flush_docs_paragraph(&mut output, &mut paragraph, page_rel, remap)?;
            if list_kind.is_some_and(|current| current != ordered) {
                close_docs_list(&mut output, &mut list_kind);
            }
            if list_kind.is_none() {
                append_docs_text(&mut output, if ordered { "<ol>\n" } else { "<ul>\n" })?;
                list_kind = Some(ordered);
            }
            append_docs_text(&mut output, "<li>")?;
            append_inline_markup_for_page(&mut output, item, page_rel, remap)?;
            append_docs_text(&mut output, "</li>\n")?;
            continue;
        }
        if trimmed.is_empty() {
            flush_docs_paragraph(&mut output, &mut paragraph, page_rel, remap)?;
            close_docs_list(&mut output, &mut list_kind);
            continue;
        }
        if trimmed.starts_with('<') {
            flush_docs_paragraph(&mut output, &mut paragraph, page_rel, remap)?;
            close_docs_list(&mut output, &mut list_kind);
            let rewritten = rewrite_docs_html_targets(trimmed, page_rel, remap)?;
            append_docs_text(&mut output, &rewritten)?;
            append_docs_text(&mut output, "\n")?;
            continue;
        }
        if !paragraph.is_empty() {
            paragraph.push(' ');
        }
        paragraph.push_str(trimmed);
    }
    if code_fence.is_some() {
        return None;
    }
    flush_docs_paragraph(&mut output, &mut paragraph, page_rel, remap)?;
    close_docs_list(&mut output, &mut list_kind);
    Some(output)
}

/// Extracts one supported unordered or ordered Markdown list item.
fn markdown_list_item(line: &str) -> Option<(bool, &str)> {
    if let Some(item) = line.strip_prefix("- ") {
        return Some((false, item));
    }
    let (number, item) = line.split_once(". ")?;
    (!number.is_empty() && number.bytes().all(|byte| byte.is_ascii_digit())).then_some((true, item))
}

/// Extracts a Markdown heading level and its title from one source line.
fn markdown_heading(line: &str) -> Option<(usize, &str)> {
    let level = line.bytes().take_while(|byte| *byte == b'#').count();
    (1..=6)
        .contains(&level)
        .then(|| {
            line.get(level..)?
                .strip_prefix(' ')
                .map(|title| (level, title.trim()))
        })
        .flatten()
}

/// Flushes one paragraph through the page-aware inline renderer.
fn flush_docs_paragraph(
    output: &mut String,
    paragraph: &mut String,
    page_rel: &str,
    remap: Option<&DocsOutputRemap>,
) -> Option<()> {
    if paragraph.trim().is_empty() {
        paragraph.clear();
        return Some(());
    }
    append_docs_text(output, "<p>")?;
    append_inline_markup_for_page(output, paragraph.trim(), page_rel, remap)?;
    append_docs_text(output, "</p>\n")?;
    paragraph.clear();
    Some(())
}

/// Closes an open Markdown list.
fn close_docs_list(output: &mut String, list_kind: &mut Option<bool>) {
    if let Some(ordered) = list_kind.take() {
        let _ = dbuf_append(output, if ordered { "</ol>\n" } else { "</ul>\n" });
    }
}

/// Renders inline Markdown while rewriting local links for one output page.
fn append_inline_markup_for_page(
    output: &mut String,
    text: &str,
    page_rel: &str,
    remap: Option<&DocsOutputRemap>,
) -> Option<()> {
    if text.len() > 256 * 1024 {
        return None;
    }
    let mut cursor = 0usize;
    while cursor < text.len() {
        let remainder = &text[cursor..];
        if let Some(close) = remainder
            .strip_prefix('`')
            .and_then(|value| value.find('`'))
        {
            append_docs_text(output, "<code>")?;
            append_docs_text(output, &html_escape(&remainder[1..close + 1]))?;
            append_docs_text(output, "</code>")?;
            cursor += close + 2;
            continue;
        }
        if let Some(close) = remainder
            .strip_prefix("**")
            .and_then(|value| value.find("**"))
        {
            append_docs_text(output, "<strong>")?;
            append_inline_markup_for_page(output, &remainder[2..close + 2], page_rel, remap)?;
            append_docs_text(output, "</strong>")?;
            cursor += close + 4;
            continue;
        }
        if remainder.starts_with('[')
            && let Some(label_end) = remainder.find("](")
            && let Some(target_end) = remainder[label_end + 2..].find(')')
        {
            let target_end = label_end + 2 + target_end;
            let target = &remainder[label_end + 2..target_end];
            let href = rewrite_docs_target(target, page_rel, remap)?;
            append_docs_text(output, "<a href=\"")?;
            append_docs_text(output, &html_escape(&href))?;
            append_docs_text(output, "\">")?;
            append_inline_markup_for_page(output, &remainder[1..label_end], page_rel, remap)?;
            append_docs_text(output, "</a>")?;
            cursor += target_end + 1;
            continue;
        }
        let next = [
            remainder.find('`'),
            remainder.find("**"),
            remainder.find('['),
        ]
        .into_iter()
        .flatten()
        .min()
        .unwrap_or(remainder.len());
        append_docs_text(output, &html_escape(&remainder[..next]))?;
        cursor += next.max(1);
    }
    Some(())
}

/// Rewrites local HTML attribute targets relative to a generated docs page.
fn rewrite_docs_html_targets(
    line: &str,
    page_rel: &str,
    remap: Option<&DocsOutputRemap>,
) -> Option<String> {
    let mut output = String::with_capacity(line.len() + 32);
    let mut cursor = 0usize;
    while cursor < line.len() {
        let remainder = &line[cursor..];
        let candidates = [remainder.find("src=\""), remainder.find("href=\"")];
        let Some(offset) = candidates.into_iter().flatten().min() else {
            output.push_str(remainder);
            break;
        };
        let attribute_end = offset + 5;
        output.push_str(&remainder[..attribute_end]);
        let value_start = attribute_end;
        let value = &remainder[value_start..];
        let close = value.find('\"')?;
        let target = &value[..close];
        output.push_str(&html_escape(&rewrite_docs_target(target, page_rel, remap)?));
        output.push('\"');
        cursor += value_start + close + 1;
    }
    Some(output)
}

/// Rewrites one safe local docs link or asset target.
fn rewrite_docs_target(
    target: &str,
    page_rel: &str,
    remap: Option<&DocsOutputRemap>,
) -> Option<String> {
    let (base, suffix) = target.split_once('#').map_or((target, ""), |(base, hash)| {
        (base, &target[target.len() - hash.len() - 1..])
    });
    if base.is_empty()
        || base.starts_with('/')
        || base.starts_with('#')
        || base.contains("://")
        || base.starts_with("mailto:")
        || base.starts_with("javascript:")
        || base.starts_with("data:")
    {
        return Some(target.to_owned());
    }
    let resolved_base =
        resolve_docs_relative_target(page_rel, base).unwrap_or_else(|| base.to_owned());
    let output_target = if resolved_base.ends_with(".md") {
        docs_html_output_rel_with_remap(&resolved_base, remap)?
    } else {
        resolved_base
    };
    Some(format!(
        "{}{}",
        relative_href_from_output(page_rel, &output_target)?,
        suffix
    ))
}

/// Renders template value.
fn render_template_value(template: &str, values: &[(&str, &str, bool)]) -> Option<String> {
    let mut output = String::with_capacity(template.len() + 128);
    let mut cursor = 0usize;
    while cursor < template.len() {
        let Some(relative_open) = template[cursor..].find('{') else {
            output.push_str(&template[cursor..]);
            break;
        };
        let open = cursor + relative_open;
        output.push_str(&template[cursor..open]);
        let key_start = open + 1;
        let close = template[key_start..].find('}')? + key_start;
        let raw_key = &template[key_start..close];
        let (key, explicit_html) = raw_key
            .strip_prefix("html:")
            .map_or((raw_key, false), |value| (value, true));
        if let Some((_, value, is_html)) = values.iter().find(|(name, _, _)| *name == key) {
            if explicit_html || *is_html {
                output.push_str(value);
            } else {
                output.push_str(&html_escape(value));
            }
        } else {
            output.push_str(&template[open..=close]);
        }
        if output.len() > MAX_DOC_TEXT_BYTES {
            return None;
        }
        cursor = close + 1;
    }
    Some(output)
}

/// Performs docs render sidebar.
///
/// # Parameters
///
/// - `sidebar_template_html`: Input consumed by [`crate::docs::docs_render_sidebar`].
/// - `sidebar_item_template_html`: Input consumed by [`crate::docs::docs_render_sidebar`].
/// - `sidebar_title`: Input consumed by [`crate::docs::docs_render_sidebar`].
/// - `nav_entries`: Input consumed by [`crate::docs::docs_render_sidebar`].
/// - `current_page_html_rel`: Input consumed by [`crate::docs::docs_render_sidebar`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_render_sidebar`] 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::docs::docs_render_sidebar`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_render_sidebar(todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_render_sidebar(
    sidebar_template_html: &str,
    sidebar_item_template_html: &str,
    sidebar_group_template_html: &str,
    sidebar_title: &str,
    nav_entries: &[DocsNavEntry],
    current_page_html_rel: &str,
) -> Option<String> {
    if sidebar_template_html.is_empty()
        || sidebar_item_template_html.is_empty()
        || current_page_html_rel.is_empty()
    {
        return None;
    }
    let nav_nodes = docs_nav_tree(nav_entries)?;
    let mut items = String::new();
    let mut group_id = 0usize;
    for node in nav_nodes.iter().take(MAX_DOC_FILES) {
        let item = docs_render_sidebar_node(
            sidebar_item_template_html,
            sidebar_group_template_html,
            node,
            current_page_html_rel,
            &mut group_id,
        )?;
        items.push_str(&item);
        if items.len() > MAX_DOC_TEXT_BYTES {
            return None;
        }
    }
    let title_block = if sidebar_title.is_empty() {
        String::new()
    } else {
        format!(
            "<div class=\"docs-sidebar-title\">{}</div>\n",
            html_escape(sidebar_title)
        )
    };
    render_template_value(
        sidebar_template_html,
        &[
            ("title", sidebar_title, false),
            ("title_block", &title_block, true),
            ("items", &items, true),
        ],
    )
}

fn docs_nav_tree(nav_entries: &[DocsNavEntry]) -> Option<Vec<DocsNavNode>> {
    let mut index = 0usize;
    docs_nav_parse_nodes(nav_entries, &mut index, 0)
}

fn docs_nav_parse_nodes(
    nav_entries: &[DocsNavEntry],
    index: &mut usize,
    depth: usize,
) -> Option<Vec<DocsNavNode>> {
    let mut nodes = Vec::new();
    while *index < nav_entries.len() {
        let entry = nav_entries.get(*index)?;
        if entry.depth < depth {
            break;
        }
        if entry.depth > depth {
            return None;
        }
        let mut node = DocsNavNode {
            path: entry.path.clone(),
            label: entry.label.clone(),
            depth: entry.depth,
            children: Vec::new(),
        };
        *index += 1;
        if *index < nav_entries.len() && nav_entries.get(*index)?.depth > depth {
            node.children = docs_nav_parse_nodes(nav_entries, index, depth + 1)?;
        }
        nodes.push(node);
    }
    Some(nodes)
}

fn docs_sidebar_href(current_page_html_rel: &str, path: &str) -> Option<String> {
    if path == "index.html" {
        let depth = docs_page_depth(current_page_html_rel);
        if depth == 0 {
            Some("index.html".to_owned())
        } else {
            Some(format!("{}index.html", "../".repeat(depth)))
        }
    } else {
        relative_href_from_output(current_page_html_rel, path)
    }
}

fn docs_nav_node_contains_current(node: &DocsNavNode, current_page_html_rel: &str) -> bool {
    node.path == current_page_html_rel
        || node
            .children
            .iter()
            .any(|child| docs_nav_node_contains_current(child, current_page_html_rel))
}

fn docs_nav_default_open(node: &DocsNavNode) -> bool {
    node.depth == 0 && node.label == "Start Here"
}

fn docs_render_sidebar_node(
    sidebar_item_template_html: &str,
    sidebar_group_template_html: &str,
    node: &DocsNavNode,
    current_page_html_rel: &str,
    group_id: &mut usize,
) -> Option<String> {
    let href = docs_sidebar_href(current_page_html_rel, &node.path)?;
    let current = node.path == current_page_html_rel;
    let contains_current = docs_nav_node_contains_current(node, current_page_html_rel);
    let depth_class = format!("docs-depth-{}", node.depth);
    let active_suffix = if current { " is-active" } else { "" };
    let active_attr = if current {
        " aria-current=\"page\""
    } else {
        ""
    };
    let item_link = render_template_value(
        sidebar_item_template_html,
        &[
            ("href", &href, false),
            ("label", &node.label, false),
            ("depth_class", &depth_class, false),
            ("active_suffix", active_suffix, false),
            ("active_attr", active_attr, true),
        ],
    )?;
    if node.children.is_empty() {
        return Some(item_link);
    }
    *group_id = group_id.saturating_add(1);
    let current_group_id = format!("docs-nav-group-{}", group_id);
    let is_open = docs_nav_default_open(node) || contains_current;
    let expanded_attr = if is_open { "true" } else { "false" };
    let open_class = if is_open { " is-open" } else { "" };
    let mut children_html = String::new();
    for child in node.children.iter().take(MAX_DOC_FILES) {
        let child_html = docs_render_sidebar_node(
            sidebar_item_template_html,
            sidebar_group_template_html,
            child,
            current_page_html_rel,
            group_id,
        )?;
        children_html.push_str(&child_html);
        if children_html.len() > MAX_DOC_TEXT_BYTES {
            return None;
        }
    }
    render_template_value(
        sidebar_group_template_html,
        &[
            ("depth", &node.depth.to_string(), false),
            ("open_class", open_class, false),
            ("expanded", expanded_attr, false),
            ("group_id", &current_group_id, false),
            ("label", &node.label, false),
            ("item_link", &item_link, true),
            ("children", &children_html, true),
        ],
    )
}

#[allow(clippy::too_many_arguments)]
/// Performs docs render page.
///
/// # Parameters
///
/// - `template_html`: Input consumed by [`crate::docs::docs_render_page`].
/// - `title`: Input consumed by [`crate::docs::docs_render_page`].
/// - `sidebar_html`: Input consumed by [`crate::docs::docs_render_page`].
/// - `body_html`: Input consumed by [`crate::docs::docs_render_page`].
/// - `back_href`: Input consumed by [`crate::docs::docs_render_page`].
/// - `wordmark_src`: Input consumed by [`crate::docs::docs_render_page`].
/// - `favicon_src`: Input consumed by [`crate::docs::docs_render_page`].
/// - `stylesheet_src`: Input consumed by [`crate::docs::docs_render_page`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_render_page`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_render_page(todo!(), todo!(), todo!(), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_render_page(
    template_html: &str,
    title: &str,
    sidebar_html: &str,
    body_html: &str,
    back_href: &str,
    wordmark_src: &str,
    favicon_src: &str,
    stylesheet_src: &str,
) -> Option<String> {
    if template_html.is_empty() {
        return None;
    }
    render_template_value(
        template_html,
        &[
            ("title", title, false),
            ("sidebar", sidebar_html, true),
            ("body", body_html, true),
            ("back_href", back_href, false),
            ("wordmark_src", wordmark_src, false),
            ("favicon_src", favicon_src, false),
            ("stylesheet_src", stylesheet_src, false),
        ],
    )
}

/// Collects md files.
///
/// # Parameters
///
/// - `dir_path`: Input consumed by [`crate::docs::collect_md_files`].
/// - `base_prefix`: Input consumed by [`crate::docs::collect_md_files`].
/// - `depth`: Input consumed by [`crate::docs::collect_md_files`].
/// - `max_depth`: Input consumed by [`crate::docs::collect_md_files`].
/// - `files`: Input consumed by [`crate::docs::collect_md_files`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::collect_md_files`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::docs::collect_md_files`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::collect_md_files(todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn collect_md_files(
    dir_path: &Path,
    base_prefix: &str,
    depth: usize,
    max_depth: usize,
    files: &mut Vec<(String, PathBuf)>,
) -> bool {
    if depth > max_depth || files.len() > MAX_DOC_FILES {
        return false;
    }
    let Ok(entries) = fs::read_dir(dir_path) else {
        return true;
    };
    for entry in entries {
        let Ok(entry) = entry else {
            return false;
        };
        let path = entry.path();
        let Some(name) = entry.file_name().to_str().map(ToOwned::to_owned) else {
            continue;
        };
        if name == "." || name == ".." {
            continue;
        }
        let relative = if base_prefix.is_empty() {
            name.clone()
        } else {
            format!("{base_prefix}/{name}")
        };
        if path.is_dir() {
            if !collect_md_files(&path, &relative, depth + 1, max_depth, files) {
                return false;
            }
        } else if name.ends_with(".md") {
            if files.len() >= MAX_DOC_FILES {
                return false;
            }
            files.push((relative, path));
        }
    }
    true
}

/// Performs docs page title.
///
/// # Parameters
///
/// - `markdown_text`: Input consumed by [`crate::docs::docs_page_title`].
/// - `rel_path`: Input consumed by [`crate::docs::docs_page_title`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::docs::docs_page_title`] 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::docs::docs_page_title`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_page_title(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_page_title(markdown_text: Option<&str>, rel_path: Option<&str>) -> Option<String> {
    if let Some(text) = markdown_text {
        for line in text.lines() {
            if let Some(title) = line
                .strip_prefix("# ")
                .map(str::trim)
                .filter(|value| !value.is_empty())
            {
                return Some(title.to_owned());
            }
        }
    }
    let path = rel_path.unwrap_or_default();
    let name = Path::new(path)
        .file_name()
        .and_then(|value| value.to_str())
        .unwrap_or("");
    if name.is_empty() {
        return Some("Pharos Documentation".to_owned());
    }
    if matches!(name, "README.md" | "index.md") {
        return if let Some(parent) = Path::new(path)
            .parent()
            .filter(|value| !value.as_os_str().is_empty())
        {
            Some(
                parent
                    .file_name()?
                    .to_string_lossy()
                    .replace(['-', '_'], " "),
            )
        } else {
            Some("Documentation".to_owned())
        };
    }
    let stem = name.strip_suffix(".md").unwrap_or(name);
    let mut chars = stem.chars();
    let mut title = chars
        .next()
        .map(|value| value.to_ascii_uppercase())
        .into_iter()
        .chain(chars)
        .collect::<String>();
    title = title.replace(['-', '_'], " ");
    Some(title)
}

/// Performs docs nav collect entries local.
///
/// # Parameters
///
/// - `items`: Input consumed by [`crate::docs::docs_nav_collect_entries_local`].
/// - `depth`: Input consumed by [`crate::docs::docs_nav_collect_entries_local`].
/// - `entries`: Input consumed by [`crate::docs::docs_nav_collect_entries_local`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::docs::docs_nav_collect_entries_local`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::docs::docs_nav_collect_entries_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_docs::docs::docs_nav_collect_entries_local(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::docs`] for adjacent helpers that share the same runtime surface.
pub fn docs_nav_collect_entries_local(
    items: &Value,
    depth: usize,
    entries: &mut Vec<DocsNavEntry>,
) -> bool {
    let Some(items) = items.as_array() else {
        return true;
    };
    for item in items {
        if let (Some(path), Some(label)) = (
            item.get("path")
                .and_then(Value::as_str)
                .filter(|value| !value.is_empty()),
            item.get("label")
                .and_then(Value::as_str)
                .filter(|value| !value.is_empty()),
        ) {
            if entries.len() >= MAX_DOC_FILES {
                return false;
            }
            let Some(path) = docs_html_output_rel_with_remap(path, None) else {
                return false;
            };
            entries.push(DocsNavEntry {
                path,
                label: label.to_owned(),
                depth,
            });
        }
        if let Some(children) = item.get("children")
            && !docs_nav_collect_entries_local(children, depth + 1, entries)
        {
            return false;
        }
    }
    true
}

#[cfg(test)]
mod tests {
    use super::{
        docs_markdown_to_html, docs_markdown_to_html_with_remap_for_page, docs_root_href,
        docs_sidebar_href,
    };

    /// Keeps authored HTML inert and readable inside fenced examples.
    #[test]
    fn markdown_renders_fenced_code_as_escaped_preformatted_text() {
        let html = docs_markdown_to_html("```html\n<form action=\"/cart\">\n```\n")
            .expect("rendered markdown");
        assert_eq!(
            html,
            "<pre><code class=\"language-html\">&lt;form action=&quot;/cart&quot;&gt;\n</code></pre>\n"
        );
    }

    /// Preserves the semantic distinction between numbered steps and bullets.
    #[test]
    fn markdown_renders_ordered_and_unordered_lists_separately() {
        let html = docs_markdown_to_html("1. Run demo\n2. Add pack\n\n- Page\n- Form\n")
            .expect("rendered markdown");
        assert!(html.contains("<ol>\n<li>Run demo</li>\n<li>Add pack</li>\n</ol>"));
        assert!(html.contains("<ul>\n<li>Page</li>\n<li>Form</li>\n</ul>"));
    }

    #[test]
    /// Performs markdown rewrites nested relative links against the current page.
    fn markdown_rewrites_nested_relative_links_against_the_current_page() {
        let html = docs_markdown_to_html_with_remap_for_page(
            "Continue into [Why Pharos changes the app boundary](../why-pharos.md).\n",
            None,
            "tutorials/ucal.html",
        )
        .expect("rendered markdown");
        assert!(
            html.contains("<a href=\"../why-pharos.html\">Why Pharos changes the app boundary</a>")
        );
        assert!(!html.contains("../../why-pharos.html"));
    }

    #[test]
    /// Performs docs root href matches mounted docs home route shape.
    fn docs_root_href_matches_mounted_docs_home_route_shape() {
        assert_eq!(docs_root_href("index.html").as_deref(), Some("index.html"));
        assert_eq!(
            docs_root_href("why-pharos.html").as_deref(),
            Some("index.html")
        );
        assert_eq!(
            docs_root_href("tutorials/ucal.html").as_deref(),
            Some("../index.html")
        );
        assert_eq!(
            docs_root_href("reference/library-reference.html").as_deref(),
            Some("../index.html")
        );
    }

    #[test]
    /// Keeps generated sidebar home links explicit instead of rendering dot-path hrefs.
    fn docs_sidebar_href_uses_explicit_home_file() {
        assert_eq!(
            docs_sidebar_href("index.html", "index.html").as_deref(),
            Some("index.html")
        );
        assert_eq!(
            docs_sidebar_href("reference/index.html", "index.html").as_deref(),
            Some("../index.html")
        );
    }
}