pharos_native/runtime/

generated.rs

use std::fs;
use std::path::Path;

use serde_json::{Map, Value};

use crate::config::AppRuntime;

use super::business::tenant_id_for_business_base;
use super::dynamic::generated_surface_label;

#[derive(Debug, Clone, Default, Eq, PartialEq)]
/// Public struct `GeneratedSurfaceApiMatchRuntime` used by this module.
///
/// # Fields
///
/// - `fixture_root`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `state_root`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `form_root`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `surface_root`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `context_root`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `surface_id`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `operation_name`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `business_slug`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `fixture_path`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `form_fixture_path`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `context_id`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
/// - `tenant_id`: Stored field on `GeneratedSurfaceApiMatchRuntime`.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = std::mem::size_of::<pharos_native::runtime::generated::GeneratedSurfaceApiMatchRuntime>();
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for constructors, helpers, and neighboring runtime types.
pub struct GeneratedSurfaceApiMatchRuntime {
    pub fixture_root: Value,
    pub state_root: Value,
    pub form_root: Option<Value>,
    pub surface_root: Value,
    pub context_root: Value,
    pub surface_id: Option<String>,
    pub operation_name: Option<String>,
    pub business_slug: Option<String>,
    pub fixture_path: Option<String>,
    pub form_fixture_path: Option<String>,
    pub context_id: i64,
    pub tenant_id: i64,
}

/// Returns the JSON long.
fn json_long(value: &Value, key: &str, default_value: i64) -> i64 {
    value
        .get(key)
        .and_then(Value::as_i64)
        .unwrap_or(default_value)
}

/// Reads JSON file.
fn read_json_file(path: &Path) -> Option<Value> {
    serde_json::from_str(&fs::read_to_string(path).ok()?).ok()
}

/// Performs truthy text.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::runtime::generated::truthy_text`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::generated::truthy_text`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::truthy_text("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn truthy_text(text: &str) -> bool {
    matches!(
        text.trim().to_ascii_lowercase().as_str(),
        "true" | "1" | "yes" | "on"
    )
}

/// Performs digits only text.
fn digits_only_text(text: &str) -> bool {
    !text.is_empty() && text.chars().all(|ch| ch.is_ascii_digit())
}

/// Performs value to string.
fn value_to_string(value: &Value) -> String {
    match value {
        Value::Null => String::new(),
        Value::String(text) => text.clone(),
        Value::Bool(flag) => flag.to_string(),
        Value::Number(number) => number.to_string(),
        _ => serde_json::to_string(value).unwrap_or_default(),
    }
}

/// Performs fixture path.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::generated::fixture_path`].
/// - `relative_path`: Input consumed by [`crate::runtime::generated::fixture_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::fixture_path`] 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::runtime::generated::fixture_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::fixture_path(todo!(), "page");
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn fixture_path(app: &AppRuntime, relative_path: &str) -> Option<String> {
    if relative_path.is_empty() {
        return None;
    }
    for base in [app.artifact_dir.as_deref(), app.app_root.as_deref()] {
        let Some(base) = base.filter(|value| !value.is_empty()) else {
            continue;
        };
        let candidate = Path::new(base).join(relative_path);
        if candidate.exists() {
            return Some(candidate.to_string_lossy().into_owned());
        }
    }
    None
}

/// Performs generated surface fixture path.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::generated::generated_surface_fixture_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::generated_surface_fixture_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_fixture_path(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_fixture_path(app: &AppRuntime) -> Option<String> {
    fixture_path(app, "data/contracts/generated-surfaces.json")
}

/// Performs generated manage path segment.
fn generated_manage_path_segment(manage_path: &str) -> Option<String> {
    manage_path
        .trim_matches('/')
        .split('/')
        .filter(|segment| !segment.is_empty())
        .rev()
        .find(|segment| !segment.starts_with('{') && !segment.starts_with(':'))
        .map(ToOwned::to_owned)
}

/// Builds the runtime generated admin surface find.
///
/// # Parameters
///
/// - `fixture_root`: Input consumed by [`crate::runtime::generated::runtime_generated_admin_surface_find`].
/// - `surface_kind`: Input consumed by [`crate::runtime::generated::runtime_generated_admin_surface_find`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::runtime_generated_admin_surface_find`] 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::runtime::generated::runtime_generated_admin_surface_find`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::runtime_generated_admin_surface_find(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_admin_surface_find<'a>(
    fixture_root: &'a Value,
    surface_kind: &str,
) -> Option<&'a Value> {
    if surface_kind.is_empty() {
        return None;
    }
    fixture_root
        .get("surfaces")
        .and_then(Value::as_array)?
        .iter()
        .find(|surface| {
            if surface.get("surface_kind").and_then(Value::as_str) != Some("generated_admin") {
                return false;
            }
            let manage_path = surface
                .get("operations")
                .and_then(|value| value.get("manage"))
                .and_then(|value| value.get("path"))
                .and_then(Value::as_str);
            manage_path
                .and_then(generated_manage_path_segment)
                .as_deref()
                == Some(surface_kind)
        })
}

/// Performs dynamic dispatch extract param.
///
/// # Parameters
///
/// - `route_pattern`: Input consumed by [`crate::runtime::generated::dynamic_dispatch_extract_param`].
/// - `request_path`: Input consumed by [`crate::runtime::generated::dynamic_dispatch_extract_param`].
/// - `param_name`: Input consumed by [`crate::runtime::generated::dynamic_dispatch_extract_param`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::dynamic_dispatch_extract_param`] 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::runtime::generated::dynamic_dispatch_extract_param`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::dynamic_dispatch_extract_param(todo!(), "/", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_dispatch_extract_param(
    route_pattern: &str,
    request_path: &str,
    param_name: &str,
) -> Option<String> {
    if route_pattern.is_empty() || request_path.is_empty() || param_name.is_empty() {
        return None;
    }
    let request_path = request_path.split('?').next().unwrap_or_default();
    let pattern_segments: Vec<&str> = route_pattern.trim_matches('/').split('/').collect();
    let request_segments: Vec<&str> = request_path.trim_matches('/').split('/').collect();
    if pattern_segments.len() != request_segments.len() {
        return None;
    }
    for (pattern, actual) in pattern_segments.iter().zip(request_segments.iter()) {
        if let Some(name) = pattern.strip_prefix(':') {
            if name == param_name {
                return Some((*actual).to_owned());
            }
            continue;
        }
        if let Some(name) = pattern
            .strip_prefix('{')
            .and_then(|value| value.strip_suffix('}'))
        {
            if name == param_name {
                return Some((*actual).to_owned());
            }
            continue;
        }
        if pattern != actual {
            return None;
        }
    }
    None
}

/// Performs dynamic find business by slug.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::runtime::generated::dynamic_find_business_by_slug`].
/// - `business_slug`: Input consumed by [`crate::runtime::generated::dynamic_find_business_by_slug`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::dynamic_find_business_by_slug`] 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::runtime::generated::dynamic_find_business_by_slug`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::dynamic_find_business_by_slug(std::path::Path::new("."), "demo");
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn dynamic_find_business_by_slug<'a>(
    root: &'a Value,
    business_slug: &str,
) -> Option<&'a Value> {
    pharos_runtime_business::dynamic_find_business_by_slug(root, business_slug)
}

/// Builds the runtime generated surface operation path.
///
/// # Parameters
///
/// - `surface_root`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_operation_path`].
/// - `business_slug`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_operation_path`].
/// - `operation_name`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_operation_path`].
/// - `identity_value`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_operation_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::runtime_generated_surface_operation_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::runtime_generated_surface_operation_path(todo!(), "demo", todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_surface_operation_path(
    surface_root: &Value,
    business_slug: Option<&str>,
    operation_name: &str,
    identity_value: Option<&str>,
) -> Option<String> {
    if operation_name.is_empty() || !surface_root.is_object() {
        return None;
    }
    let template_path = surface_root
        .get("operations")
        .and_then(|value| value.get(operation_name))
        .and_then(|value| value.get("path"))
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())?;
    let context_param = surface_root
        .get("context_binding")
        .and_then(|value| value.get("param"))
        .and_then(Value::as_str)
        .unwrap_or("business_slug");
    let identity_param = surface_root
        .get("identity_param")
        .and_then(Value::as_str)
        .unwrap_or("id");
    Some(
        template_path
            .replace(
                &format!("{{{context_param}}}"),
                business_slug.unwrap_or_default(),
            )
            .replace(
                &format!("{{{identity_param}}}"),
                identity_value.unwrap_or_default(),
            ),
    )
}

/// Renders template text.
fn render_template_text(template_text: &str, params: &Map<String, Value>) -> Option<String> {
    let mut out = String::with_capacity(template_text.len() + 64);
    let mut cursor = 0usize;
    while let Some(relative_open) = template_text[cursor..].find('{') {
        let open = cursor + relative_open;
        out.push_str(&template_text[cursor..open]);
        let key_start = open + 1;
        let relative_close = template_text[key_start..].find('}')?;
        let close = key_start + relative_close;
        let mut key = &template_text[key_start..close];
        let raw_html = if let Some(stripped) = key.strip_prefix("html:") {
            key = stripped;
            true
        } else if let Some(stripped) = key.strip_prefix("path:") {
            key = stripped;
            false
        } else if let Some(stripped) = key.strip_prefix("url:") {
            key = stripped;
            false
        } else {
            false
        };
        let value = params
            .get(key)
            .map_or_else(String::new, |value| match value {
                Value::Null => String::new(),
                Value::String(text) => text.clone(),
                Value::Bool(flag) => flag.to_string(),
                Value::Number(number) => number.to_string(),
                _ => serde_json::to_string(value).unwrap_or_default(),
            });
        if raw_html {
            out.push_str(&value);
        } else {
            out.push_str(
                &value
                    .replace('&', "&amp;")
                    .replace('<', "&lt;")
                    .replace('>', "&gt;")
                    .replace('"', "&quot;"),
            );
        }
        cursor = close + 1;
    }
    out.push_str(&template_text[cursor..]);
    Some(out)
}

/// Renders generated admin fragment from value runtime.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::runtime::generated::render_generated_admin_fragment_from_value_runtime`].
/// - `relative_path`: Input consumed by [`crate::runtime::generated::render_generated_admin_fragment_from_value_runtime`].
/// - `params`: Input consumed by [`crate::runtime::generated::render_generated_admin_fragment_from_value_runtime`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::render_generated_admin_fragment_from_value_runtime`] 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::runtime::generated::render_generated_admin_fragment_from_value_runtime`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::render_generated_admin_fragment_from_value_runtime(std::path::Path::new("apps/dev_docs"), "page", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn render_generated_admin_fragment_from_value_runtime(
    app_root: &Path,
    relative_path: &str,
    params: &Map<String, Value>,
) -> Option<String> {
    if relative_path.is_empty() || app_root.as_os_str().is_empty() {
        return None;
    }
    let template_text =
        super::cache::template_source_lookup(app_root, relative_path).or_else(|| {
            let text = fs::read_to_string(app_root.join(relative_path)).ok()?;
            super::cache::template_source_store(app_root, relative_path, &text);
            Some(text)
        })?;
    render_template_text(&template_text, params)
}

/// Builds the runtime generated surface append record actions HTML.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_append_record_actions_html`].
/// - `app_root`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_append_record_actions_html`].
/// - `edit_path`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_append_record_actions_html`].
/// - `delete_path`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_append_record_actions_html`].
/// - `delete_button_label`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_append_record_actions_html`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::generated::runtime_generated_surface_append_record_actions_html`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::runtime_generated_surface_append_record_actions_html(&mut [], std::path::Path::new("apps/dev_docs"), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_surface_append_record_actions_html(
    buffer: &mut String,
    app_root: &Path,
    edit_path: Option<&str>,
    delete_path: Option<&str>,
    delete_button_label: Option<&str>,
) -> bool {
    if app_root.as_os_str().is_empty() {
        return false;
    }
    let mut edit_link_html = String::new();
    let mut delete_link_html = String::new();

    if let Some(edit_path) = edit_path.filter(|value| !value.is_empty()) {
        let params = Map::from_iter([
            (
                "button_class".to_owned(),
                Value::String("btn-secondary".to_owned()),
            ),
            (
                "action_path".to_owned(),
                Value::String(edit_path.to_owned()),
            ),
            ("button_label".to_owned(), Value::String("Edit".to_owned())),
        ]);
        let Some(rendered) = render_generated_admin_fragment_from_value_runtime(
            app_root,
            "templates/shared/fragments/action_link.html",
            &params,
        ) else {
            return false;
        };
        edit_link_html = rendered;
    }

    if let Some(delete_path) = delete_path.filter(|value| !value.is_empty()) {
        let params = Map::from_iter([
            (
                "button_class".to_owned(),
                Value::String("btn-danger".to_owned()),
            ),
            (
                "action_path".to_owned(),
                Value::String(delete_path.to_owned()),
            ),
            (
                "button_label".to_owned(),
                Value::String(
                    delete_button_label
                        .filter(|value| !value.is_empty())
                        .unwrap_or("Delete")
                        .to_owned(),
                ),
            ),
        ]);
        let Some(rendered) = render_generated_admin_fragment_from_value_runtime(
            app_root,
            "templates/shared/fragments/action_link.html",
            &params,
        ) else {
            return false;
        };
        delete_link_html = rendered;
    }

    let params = Map::from_iter([
        (
            "primary_action_html".to_owned(),
            Value::String(edit_link_html),
        ),
        (
            "secondary_action_html".to_owned(),
            Value::String(delete_link_html),
        ),
    ]);
    let Some(row_html) = render_generated_admin_fragment_from_value_runtime(
        app_root,
        "templates/shared/fragments/action_row.html",
        &params,
    ) else {
        return false;
    };
    buffer.push_str(&row_html);
    true
}

/// Builds the runtime generated surface append table header cells HTML.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_append_table_header_cells_html`].
/// - `columns`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_append_table_header_cells_html`].
/// - `app_root`: Input consumed by [`crate::runtime::generated::runtime_generated_surface_append_table_header_cells_html`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::generated::runtime_generated_surface_append_table_header_cells_html`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::generated::runtime_generated_surface_append_table_header_cells_html`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::runtime_generated_surface_append_table_header_cells_html(&mut [], todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn runtime_generated_surface_append_table_header_cells_html(
    buffer: &mut String,
    columns: &Value,
    app_root: &Path,
) -> bool {
    if app_root.as_os_str().is_empty() {
        return false;
    }
    let Some(columns) = columns.as_array() else {
        return true;
    };
    for column in columns {
        let mut column_label = column
            .get("label")
            .and_then(Value::as_str)
            .map(ToOwned::to_owned)
            .unwrap_or_default();
        if column_label.is_empty() {
            column_label = generated_surface_label(column.get("field").and_then(Value::as_str))
                .unwrap_or_default();
        }
        if column_label.is_empty() {
            return false;
        }
        let params = Map::from_iter([("column_label".to_owned(), Value::String(column_label))]);
        let Some(html) = render_generated_admin_fragment_from_value_runtime(
            app_root,
            "templates/generated_admin/fragments/table_header_cell.html",
            &params,
        ) else {
            return false;
        };
        buffer.push_str(&html);
    }
    true
}

/// Performs generated surface admin create load.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::generated::generated_surface_admin_create_load`].
/// - `surface_kind`: Input consumed by [`crate::runtime::generated::generated_surface_admin_create_load`].
/// - `request_path`: Input consumed by [`crate::runtime::generated::generated_surface_admin_create_load`].
/// - `route_pattern`: Input consumed by [`crate::runtime::generated::generated_surface_admin_create_load`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::generated_surface_admin_create_load`] 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::runtime::generated::generated_surface_admin_create_load`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_admin_create_load(todo!(), todo!(), "/", todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_admin_create_load(
    app: &AppRuntime,
    surface_kind: &str,
    request_path: &str,
    route_pattern: &str,
) -> Option<GeneratedSurfaceApiMatchRuntime> {
    if surface_kind.is_empty() || request_path.is_empty() || route_pattern.is_empty() {
        return None;
    }
    let app_root = app.app_root.as_deref().or(app.artifact_dir.as_deref())?;
    if super::database::relational_runtime_authority_enabled(Path::new(app_root)) {
        return None;
    }
    let generated_fixture_path = generated_surface_fixture_path(app)?;
    let form_fixture_path = fixture_path(app, "data/contracts/forms.json");
    let fixture_root = read_json_file(Path::new(&generated_fixture_path))?;
    let state_root = read_json_file(Path::new(app.state_path.as_deref()?))?;
    let form_root = form_fixture_path
        .as_deref()
        .and_then(|path| read_json_file(Path::new(path)));
    let surface_root = runtime_generated_admin_surface_find(&fixture_root, surface_kind)?.clone();
    let context_param = surface_root
        .get("context_binding")
        .and_then(|value| value.get("param"))
        .and_then(Value::as_str)?;
    let match_field = surface_root
        .get("context_binding")
        .and_then(|value| value.get("match_field"))
        .and_then(Value::as_str)?;
    let business_slug = dynamic_dispatch_extract_param(route_pattern, request_path, context_param)?;
    let _expected_create_path = runtime_generated_surface_operation_path(
        &surface_root,
        Some(&business_slug),
        "create",
        None,
    )?;
    if match_field.is_empty() {
        return None;
    }
    let business = dynamic_find_business_by_slug(&state_root, &business_slug)?;
    let context_root = Value::Object(Map::from_iter([(
        context_param.to_owned(),
        Value::String(business_slug.clone()),
    )]));
    let context_id = json_long(business, "id", 0);
    Some(GeneratedSurfaceApiMatchRuntime {
        fixture_root,
        state_root: state_root.clone(),
        form_root,
        surface_root: surface_root.clone(),
        context_root,
        surface_id: surface_root
            .get("surface_id")
            .and_then(Value::as_str)
            .map(ToOwned::to_owned),
        operation_name: Some("create".to_owned()),
        business_slug: Some(business_slug),
        fixture_path: Some(generated_fixture_path),
        form_fixture_path,
        context_id,
        tenant_id: tenant_id_for_business_base(&state_root, context_id),
    })
}

/// Performs generated surface validation report empty.
///
/// # Parameters
///
/// - `form_id`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report_empty`].
/// - `action_id`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report_empty`].
/// - `actor_scope`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report_empty`].
/// - `tenant_scope`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report_empty`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::generated_surface_validation_report_empty`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_validation_report_empty("form", todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_validation_report_empty(
    form_id: Option<&str>,
    action_id: Option<&str>,
    actor_scope: Option<&str>,
    tenant_scope: Option<&str>,
) -> Option<String> {
    serde_json::to_string(&serde_json::json!({
        "schema": "pharos.validation.report.v1",
        "report_id": "pharos.validation.report.v1",
        "form_id": form_id.unwrap_or_default(),
        "action_id": action_id.unwrap_or_default(),
        "field_errors": [],
        "form_errors": [],
        "actor_scope": actor_scope.unwrap_or("anonymous"),
        "tenant_scope": tenant_scope.unwrap_or("global"),
    }))
    .ok()
}

/// Performs generated surface validation report add field error.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report_add_field_error`].
/// - `field_id`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report_add_field_error`].
/// - `rule_id`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report_add_field_error`].
/// - `code`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report_add_field_error`].
/// - `message`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report_add_field_error`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::generated_surface_validation_report_add_field_error`] 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::runtime::generated::generated_surface_validation_report_add_field_error`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_validation_report_add_field_error("{}", "field", todo!(), todo!(), "example");
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_validation_report_add_field_error(
    report_json: &str,
    field_id: Option<&str>,
    rule_id: Option<&str>,
    code: Option<&str>,
    message: Option<&str>,
) -> Option<String> {
    let mut root = serde_json::from_str::<Value>(if report_json.is_empty() {
        "{}"
    } else {
        report_json
    })
    .ok()?;
    let root_obj = root.as_object_mut()?;
    let field_errors = root_obj
        .entry("field_errors".to_owned())
        .or_insert_with(|| Value::Array(Vec::new()))
        .as_array_mut()?;
    field_errors.push(serde_json::json!({
        "field_id": field_id.unwrap_or_default(),
        "rule_id": rule_id.unwrap_or("validation_rule"),
        "code": code.unwrap_or("invalid"),
        "message": message.unwrap_or("Invalid field value."),
    }));
    serde_json::to_string(&root).ok()
}

/// Performs generated surface submitted JSON.
///
/// # Parameters
///
/// - `surface_root`: Input consumed by [`crate::runtime::generated::generated_surface_submitted_json`].
/// - `form_root`: Input consumed by [`crate::runtime::generated::generated_surface_submitted_json`].
/// - `payload_root`: Input consumed by [`crate::runtime::generated::generated_surface_submitted_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::generated_surface_submitted_json`] 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::runtime::generated::generated_surface_submitted_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_submitted_json(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_submitted_json(
    surface_root: &Value,
    form_root: &Value,
    payload_root: &Value,
) -> Option<String> {
    let form_id = surface_root.get("form_id").and_then(Value::as_str)?;
    let form = form_root
        .get("forms")
        .and_then(Value::as_array)?
        .iter()
        .find(|item| item.get("form_id").and_then(Value::as_str) == Some(form_id))?;
    let mut out = Map::new();
    if let Some(fields) = form.get("fields").and_then(Value::as_array) {
        for item in fields {
            let Some(field_id) = item.get("field_id").and_then(Value::as_str) else {
                continue;
            };
            if let Some(value) = payload_root.get(field_id) {
                out.insert(field_id.to_owned(), value.clone());
            }
        }
    }
    if let Some(relation_inputs) = surface_root
        .get("relation_inputs")
        .and_then(Value::as_array)
    {
        for item in relation_inputs {
            let Some(field_name) = item.get("field").and_then(Value::as_str) else {
                continue;
            };
            if let Some(value) = payload_root.get(field_name) {
                out.insert(field_name.to_owned(), value.clone());
            }
        }
    }
    serde_json::to_string(&Value::Object(out)).ok()
}

/// Performs generated surface coerce candidate JSON.
///
/// # Parameters
///
/// - `surface_root`: Input consumed by [`crate::runtime::generated::generated_surface_coerce_candidate_json`].
/// - `candidate_json`: Input consumed by [`crate::runtime::generated::generated_surface_coerce_candidate_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::generated_surface_coerce_candidate_json`] 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::runtime::generated::generated_surface_coerce_candidate_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_coerce_candidate_json(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_coerce_candidate_json(
    surface_root: &Value,
    candidate_json: &str,
) -> Option<String> {
    let candidate_root = serde_json::from_str::<Value>(if candidate_json.is_empty() {
        "{}"
    } else {
        candidate_json
    })
    .ok()?;
    let mut out = candidate_root.as_object()?.clone();
    let Some(field_types) = surface_root.get("field_types").and_then(Value::as_object) else {
        return serde_json::to_string(&Value::Object(out)).ok();
    };
    for (field_name, type_value) in field_types {
        let Some(candidate_value) = out.get(field_name).cloned() else {
            continue;
        };
        let type_text = value_to_string(type_value);
        if type_text == "integer" {
            let text = value_to_string(&candidate_value);
            if digits_only_text(&text) {
                out.insert(
                    field_name.clone(),
                    Value::Number(text.parse::<i64>().ok()?.into()),
                );
            }
        } else if type_text == "boolean" {
            if !candidate_value.is_boolean() {
                out.insert(
                    field_name.clone(),
                    Value::Bool(truthy_text(&value_to_string(&candidate_value))),
                );
            }
        } else if type_text == "array_integer" && candidate_value.is_array() {
            let mut new_array = Vec::new();
            for entry in candidate_value.as_array()? {
                let text = value_to_string(entry);
                if digits_only_text(&text) {
                    new_array.push(Value::Number(text.parse::<i64>().ok()?.into()));
                }
            }
            out.insert(field_name.clone(), Value::Array(new_array));
        }
    }
    serde_json::to_string(&Value::Object(out)).ok()
}

/// Performs next array ID runtime local.
///
/// # Parameters
///
/// - `rows`: Input consumed by [`crate::runtime::generated::next_array_id_runtime_local`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::generated::next_array_id_runtime_local`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::generated::next_array_id_runtime_local`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::next_array_id_runtime_local(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn next_array_id_runtime_local(rows: Option<&Value>) -> i64 {
    let mut next_id = 1i64;
    if let Some(rows) = rows.and_then(Value::as_array) {
        for row in rows {
            let existing_id = json_long(row, "id", 0);
            if existing_id >= next_id {
                next_id = existing_id + 1;
            }
        }
    }
    next_id
}

/// Performs generated surface apply defaults to mut object.
///
/// # Parameters
///
/// - `target_obj`: Input consumed by [`crate::runtime::generated::generated_surface_apply_defaults_to_mut_object`].
/// - `defaults_root`: Input consumed by [`crate::runtime::generated::generated_surface_apply_defaults_to_mut_object`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::generated::generated_surface_apply_defaults_to_mut_object`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::generated::generated_surface_apply_defaults_to_mut_object`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_apply_defaults_to_mut_object(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_apply_defaults_to_mut_object(
    target_obj: &mut Map<String, Value>,
    defaults_root: Option<&Value>,
) -> bool {
    let Some(defaults_root) = defaults_root.and_then(Value::as_object) else {
        return true;
    };
    for (field_name, value) in defaults_root {
        if !target_obj.contains_key(field_name) {
            target_obj.insert(field_name.clone(), value.clone());
        }
    }
    true
}

/// Performs generated surface validation report has errors.
///
/// # Parameters
///
/// - `report_json`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report_has_errors`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::generated::generated_surface_validation_report_has_errors`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::generated::generated_surface_validation_report_has_errors`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_validation_report_has_errors("{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_validation_report_has_errors(report_json: &str) -> bool {
    let Ok(root) = serde_json::from_str::<Value>(if report_json.is_empty() {
        "{}"
    } else {
        report_json
    }) else {
        return false;
    };
    let field_errors = root
        .get("field_errors")
        .and_then(Value::as_array)
        .map(Vec::len)
        .unwrap_or(0);
    let form_errors = root
        .get("form_errors")
        .and_then(Value::as_array)
        .map(Vec::len)
        .unwrap_or(0);
    field_errors + form_errors > 0
}

#[derive(Debug, Clone, Eq, PartialEq)]
/// Public enum `GeneratedSurfaceCreateOutcome` used by this module.
///
/// # Variants
///
/// - `UnprocessableEntity`: Supported `GeneratedSurfaceCreateOutcome` variant.
/// - `Redirect`: Supported `GeneratedSurfaceCreateOutcome` variant.
///
/// # Examples
///
/// ```rust,ignore
/// let _ = pharos_native::runtime::generated::GeneratedSurfaceCreateOutcome::UnprocessableEntity;
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for constructors, helpers, and neighboring runtime types.
pub enum GeneratedSurfaceCreateOutcome {
    UnprocessableEntity { report_json: String },
    Redirect { location: String },
}

/// Performs persist generated surface admin create runtime.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::generated::persist_generated_surface_admin_create_runtime`].
/// - `match_record`: Input consumed by [`crate::runtime::generated::persist_generated_surface_admin_create_runtime`].
/// - `candidate_root`: Input consumed by [`crate::runtime::generated::persist_generated_surface_admin_create_runtime`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::persist_generated_surface_admin_create_runtime`] 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::runtime::generated::persist_generated_surface_admin_create_runtime`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::persist_generated_surface_admin_create_runtime(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn persist_generated_surface_admin_create_runtime(
    app: &AppRuntime,
    match_record: &GeneratedSurfaceApiMatchRuntime,
    candidate_root: &Value,
) -> Option<String> {
    let app_root = app.app_root.as_deref().or(app.artifact_dir.as_deref())?;
    if super::database::relational_runtime_authority_enabled(Path::new(app_root)) {
        return None;
    }
    let collection_name = match_record
        .surface_root
        .get("entity_collection")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())?;
    let identity_field = match_record
        .surface_root
        .get("identity_field")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .unwrap_or("id");
    let scope_field = match_record
        .surface_root
        .get("scope_field")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty());
    let auto_sequence_field = match_record
        .surface_root
        .get("auto_sequence_field")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty());
    let mut state_root = match_record.state_root.clone();
    let state_map = state_root.as_object_mut()?;
    let source_rows = state_map.get(collection_name).cloned();
    let section = state_map
        .entry(collection_name.to_owned())
        .or_insert_with(|| Value::Array(Vec::new()));
    let section_rows = section.as_array_mut()?;
    let mut item_mut = candidate_root.as_object()?.clone();
    generated_surface_apply_defaults_to_mut_object(
        &mut item_mut,
        match_record.surface_root.get("defaults"),
    );
    if let Some(scope_field) = scope_field {
        item_mut.insert(
            scope_field.to_owned(),
            Value::Number(match_record.context_id.into()),
        );
    }
    if let Some(auto_sequence_field) = auto_sequence_field
        && !item_mut.contains_key(auto_sequence_field)
    {
        let mut next_sequence = 1i64;
        if let Some(rows) = source_rows.as_ref().and_then(Value::as_array) {
            for row in rows {
                let value = json_long(row, auto_sequence_field, 0);
                let scope_value = json_long(row, scope_field.unwrap_or("business_id"), 0);
                if scope_value == match_record.context_id && value >= next_sequence {
                    next_sequence = value + 1;
                }
            }
        }
        item_mut.insert(
            auto_sequence_field.to_owned(),
            Value::Number(next_sequence.into()),
        );
    }
    let record_id = next_array_id_runtime_local(source_rows.as_ref());
    item_mut.insert(identity_field.to_owned(), Value::Number(record_id.into()));
    section_rows.push(Value::Object(item_mut));
    let state_path = Path::new(app.state_path.as_deref()?);
    write_json_file(state_path, &state_root).then(|| {
        runtime_generated_surface_operation_path(
            &match_record.surface_root,
            match_record.business_slug.as_deref(),
            "manage",
            None,
        )
        .unwrap_or_else(|| "/".to_owned())
    })
}

/// Handles generated surface admin create request.
///
/// # Parameters
///
/// - `app`: Input consumed by [`crate::runtime::generated::handle_generated_surface_admin_create_request`].
/// - `match_record`: Input consumed by [`crate::runtime::generated::handle_generated_surface_admin_create_request`].
/// - `candidate_root`: Input consumed by [`crate::runtime::generated::handle_generated_surface_admin_create_request`].
/// - `report_json`: Input consumed by [`crate::runtime::generated::handle_generated_surface_admin_create_request`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::handle_generated_surface_admin_create_request`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::handle_generated_surface_admin_create_request(todo!(), todo!(), todo!(), "{}");
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn handle_generated_surface_admin_create_request(
    app: &AppRuntime,
    match_record: &GeneratedSurfaceApiMatchRuntime,
    candidate_root: &Value,
    report_json: &str,
) -> Option<GeneratedSurfaceCreateOutcome> {
    if generated_surface_validation_report_has_errors(report_json) {
        return Some(GeneratedSurfaceCreateOutcome::UnprocessableEntity {
            report_json: report_json.to_owned(),
        });
    }
    let redirect_path =
        persist_generated_surface_admin_create_runtime(app, match_record, candidate_root)?;
    let base_path = app.base_path.clone().unwrap_or_default();
    Some(GeneratedSurfaceCreateOutcome::Redirect {
        location: format!("{base_path}{redirect_path}"),
    })
}

/// Writes JSON file.
///
/// # Parameters
///
/// - `path`: Input consumed by [`crate::runtime::generated::write_json_file`].
/// - `value`: Input consumed by [`crate::runtime::generated::write_json_file`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::generated::write_json_file`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::write_json_file(std::path::Path::new("fixture.json"), "value");
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn write_json_file(path: &Path, value: &Value) -> bool {
    if let Some(parent) = path.parent()
        && fs::create_dir_all(parent).is_err()
    {
        return false;
    }
    serde_json::to_string_pretty(value)
        .ok()
        .and_then(|text| super::fs::write_binary_file(path, text.as_bytes(), 0o640).ok())
        .is_some()
}

/// Performs generated surface delete button label.
///
/// # Parameters
///
/// - `surface`: Input consumed by [`crate::runtime::generated::generated_surface_delete_button_label`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::runtime::generated::generated_surface_delete_button_label`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_delete_button_label(todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_delete_button_label(surface: &Value) -> String {
    surface
        .get("admin")
        .and_then(|value| value.get("delete_button_label"))
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .unwrap_or("Delete")
        .to_owned()
}

/// Renders one generated-surface operation path with context and identity values.
///
/// # Parameters
///
/// - `surface`: Input consumed by [`crate::runtime::generated::generated_surface_operation_path`].
/// - `context_value`: Input consumed by [`crate::runtime::generated::generated_surface_operation_path`].
/// - `operation_name`: Input consumed by [`crate::runtime::generated::generated_surface_operation_path`].
/// - `identity_value`: Input consumed by [`crate::runtime::generated::generated_surface_operation_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::generated_surface_operation_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_operation_path(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_operation_path(
    surface: &Value,
    context_value: Option<&str>,
    operation_name: &str,
    identity_value: Option<&str>,
) -> Option<String> {
    if operation_name.is_empty() {
        return None;
    }
    let path = surface
        .get("operations")?
        .get(operation_name)?
        .get("path")?
        .as_str()?;
    let context_param = surface
        .get("context_binding")
        .and_then(|value| value.get("param"))
        .and_then(Value::as_str)
        .unwrap_or("business_slug");
    let identity_param = surface
        .get("identity_param")
        .and_then(Value::as_str)
        .unwrap_or("id");
    Some(
        path.replace(
            &format!("{{{context_param}}}"),
            context_value.unwrap_or_default(),
        )
        .replace(
            &format!("{{{identity_param}}}"),
            identity_value.unwrap_or_default(),
        ),
    )
}

/// Copies fragment tree for runtime.
///
/// # Parameters
///
/// - `source_root`: Input consumed by [`crate::runtime::generated::copy_fragment_tree_for_runtime`].
/// - `app_root`: Input consumed by [`crate::runtime::generated::copy_fragment_tree_for_runtime`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::runtime::generated::copy_fragment_tree_for_runtime`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::runtime::generated::copy_fragment_tree_for_runtime`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::copy_fragment_tree_for_runtime(todo!(), std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn copy_fragment_tree_for_runtime(source_root: &Path, app_root: &Path) -> bool {
    let mappings = [
        (
            source_root.join("templates/shared/fragments/action_link.html"),
            app_root.join("templates/shared/fragments/action_link.html"),
        ),
        (
            source_root.join("templates/shared/fragments/action_row.html"),
            app_root.join("templates/shared/fragments/action_row.html"),
        ),
        (
            source_root.join("templates/generated_admin/fragments/table_header_cell.html"),
            app_root.join("templates/generated_admin/fragments/table_header_cell.html"),
        ),
    ];
    for (source, dest) in mappings {
        let Ok(text) = fs::read_to_string(&source) else {
            return false;
        };
        if let Some(parent) = dest.parent()
            && fs::create_dir_all(parent).is_err()
        {
            return false;
        }
        if super::fs::write_file_within(app_root, &dest, text.as_bytes(), 0o644).is_err() {
            return false;
        }
    }
    true
}

/// Matches a generated operation against a bounded method and route pattern.
///
/// # Parameters
///
/// - `operation_root`: Input consumed by [`crate::runtime::generated::generated_surface_operation_matches`].
/// - `request_method`: Input consumed by [`crate::runtime::generated::generated_surface_operation_matches`].
/// - `request_path`: Input consumed by [`crate::runtime::generated::generated_surface_operation_matches`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::generated_surface_operation_matches`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_operation_matches(todo!(), todo!(), "/");
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_operation_matches(
    operation_root: &Value,
    request_method: &str,
    request_path: &str,
) -> Option<String> {
    let method = operation_root
        .get("method")
        .and_then(Value::as_str)
        .unwrap_or_default();
    let pattern = operation_root
        .get("path")
        .or_else(|| operation_root.get("route_pattern"))
        .and_then(Value::as_str)?;
    (method.eq_ignore_ascii_case(request_method)
        && super::dynamic::pattern_matches(pattern, request_path))
    .then(|| pattern.to_owned())
}

/// Builds a validation report from the declared surface and candidate payload.
///
/// # Parameters
///
/// - `surface_root`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report`].
/// - `form_root`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report`].
/// - `state_root`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report`].
/// - `context_id`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report`].
/// - `tenant_id`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report`].
/// - `candidate_json`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report`].
/// - `current_id_text`: Input consumed by [`crate::runtime::generated::generated_surface_validation_report`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::runtime::generated::generated_surface_validation_report`] 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::runtime::generated::generated_surface_validation_report`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_native::runtime::generated::generated_surface_validation_report(todo!(), todo!(), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::runtime::generated`] for adjacent helpers that share the same runtime surface.
pub fn generated_surface_validation_report(
    surface_root: &Value,
    form_root: &Value,
    state_root: &Value,
    context_id: i64,
    tenant_id: i64,
    candidate_json: &str,
    current_id_text: &str,
) -> Option<String> {
    let candidate = serde_json::from_str::<Value>(if candidate_json.is_empty() {
        "{}"
    } else {
        candidate_json
    })
    .ok()?;
    let errors = if candidate.is_object() {
        Vec::<Value>::new()
    } else {
        vec![serde_json::json!({"code":"invalid_object","message":"candidate must be an object"})]
    };
    serde_json::to_string(&serde_json::json!({"schema":"pharos.validation.report.v1","surface_id":surface_root.get("surface_id"),"form_id":form_root.get("form_id"),"context_id":context_id,"tenant_id":tenant_id,"current_id":current_id_text,"state_present":!state_root.is_null(),"field_errors":errors})).ok()
}