pharos_runtime_compiler/

declarative.rs

#![allow(clippy::too_many_arguments)]

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

use serde_json::{Map, Value};

/// Parses YAML file.
fn parse_yaml_file(path: &Path) -> Option<Value> {
    pharos_runtime_core::yaml::parse_yaml_file(path)
}

/// Builds source path.
///
/// # Parameters
///
/// - `base_dir`: Input consumed by [`crate::declarative::build_source_path`].
/// - `rel_path`: Input consumed by [`crate::declarative::build_source_path`].
/// - `ext`: Input consumed by [`crate::declarative::build_source_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::build_source_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::build_source_path(std::path::Path::new("apps"), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn build_source_path(base_dir: &Path, rel_path: &str, ext: &str) -> Option<PathBuf> {
    (!rel_path.is_empty() && !ext.is_empty()).then(|| base_dir.join(format!("{rel_path}{ext}")))
}

/// Loads YAML source.
///
/// # Parameters
///
/// - `base_dir`: Input consumed by [`crate::declarative::load_yaml_source`].
/// - `rel_path`: Input consumed by [`crate::declarative::load_yaml_source`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::load_yaml_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::declarative::load_yaml_source`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::load_yaml_source(std::path::Path::new("apps"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn load_yaml_source(base_dir: &Path, rel_path: &str) -> Option<Value> {
    if rel_path.is_empty() {
        return None;
    }
    let stem = rel_path
        .strip_suffix(".yml")
        .or_else(|| rel_path.strip_suffix(".yaml"))
        .unwrap_or(rel_path);
    let json_path = base_dir.join(format!("{stem}.json"));
    if json_path.is_file() {
        return serde_json::from_str(&fs::read_to_string(json_path).ok()?).ok();
    }
    let yaml_path = base_dir.join(format!("{stem}.yml"));
    yaml_path
        .is_file()
        .then(|| parse_yaml_file(&yaml_path))
        .flatten()
}

/// Performs declarative source load page decl.
///
/// # Parameters
///
/// - `base_dir`: Input consumed by [`crate::declarative::declarative_source_load_page_decl`].
/// - `page_name`: Input consumed by [`crate::declarative::declarative_source_load_page_decl`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_load_page_decl`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_load_page_decl(std::path::Path::new("apps"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_load_page_decl(base_dir: &Path, page_name: &str) -> Option<Value> {
    if page_name.is_empty() {
        return None;
    }
    load_yaml_source(base_dir, &format!("{page_name}.page"))
}

/// Performs declarative source load fixture.
///
/// # Parameters
///
/// - `base_dir`: Input consumed by [`crate::declarative::declarative_source_load_fixture`].
/// - `rel_path`: Input consumed by [`crate::declarative::declarative_source_load_fixture`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_load_fixture`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_load_fixture(std::path::Path::new("apps"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_load_fixture(base_dir: &Path, rel_path: &str) -> Option<Value> {
    if rel_path.is_empty() {
        return None;
    }
    if rel_path.ends_with(".json") {
        let path = build_source_path(
            base_dir,
            rel_path.strip_suffix(".json").unwrap_or(rel_path),
            ".json",
        )?;
        let metadata = fs::metadata(&path).ok()?;
        if metadata.len() > 1024 * 1024 {
            return None;
        }
        let text = fs::read_to_string(path).ok()?;
        return serde_json::from_str(&text).ok();
    }
    load_yaml_source(base_dir, rel_path.strip_suffix(".yml").unwrap_or(rel_path))
}

/// Validates the minimum fields required by a declarative app manifest.
///
/// # Parameters
///
/// - `manifest_text`: Input consumed by [`crate::declarative::declarative_manifest_has_required_fields`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::declarative_manifest_has_required_fields`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::declarative::declarative_manifest_has_required_fields`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_manifest_has_required_fields(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_manifest_has_required_fields(manifest_text: &str) -> bool {
    let Ok(root) = serde_json::from_str::<Value>(manifest_text) else {
        return false;
    };
    let Some(object) = root.as_object() else {
        return false;
    };
    ["app_id", "name", "version"].iter().all(|key| {
        object
            .get(*key)
            .and_then(Value::as_str)
            .is_some_and(|value| !value.trim().is_empty())
    })
}

/// Loads the declarative manifest text from an app root with a bounded read.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::declarative::declarative_source_load_manifest`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_load_manifest`] 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::declarative::declarative_source_load_manifest`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_load_manifest(std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_load_manifest(app_root: &Path) -> Option<String> {
    let path = app_root.join("pharos.app.json");
    let metadata = fs::metadata(&path).ok()?;
    (metadata.len() <= 1024 * 1024)
        .then(|| fs::read_to_string(path).ok())
        .flatten()
        .filter(|text| declarative_manifest_has_required_fields(text))
}

/// Performs declarative source has YAML page.
///
/// # Parameters
///
/// - `base_dir`: Input consumed by [`crate::declarative::declarative_source_has_yaml_page`].
/// - `page_name`: Input consumed by [`crate::declarative::declarative_source_has_yaml_page`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::declarative_source_has_yaml_page`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_has_yaml_page(std::path::Path::new("apps"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_has_yaml_page(base_dir: &Path, page_name: &str) -> bool {
    if page_name.is_empty() {
        return false;
    }
    build_source_path(base_dir, &format!("{page_name}.page"), ".yml")
        .is_some_and(|path| path.exists())
}

/// Performs declarative source has YAML fixture.
///
/// # Parameters
///
/// - `base_dir`: Input consumed by [`crate::declarative::declarative_source_has_yaml_fixture`].
/// - `rel_path`: Input consumed by [`crate::declarative::declarative_source_has_yaml_fixture`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::declarative_source_has_yaml_fixture`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_has_yaml_fixture(std::path::Path::new("apps"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_has_yaml_fixture(base_dir: &Path, rel_path: &str) -> bool {
    if rel_path.is_empty() {
        return false;
    }
    build_source_path(base_dir, rel_path, ".yml").is_some_and(|path| path.exists())
}

/// Finds the first object in an array whose named field equals the expected string.
///
/// # Parameters
///
/// - `array_value`: Input consumed by [`crate::declarative::declarative_source_find_object_by_string_field`].
/// - `field_name`: Input consumed by [`crate::declarative::declarative_source_find_object_by_string_field`].
/// - `expected_value`: Input consumed by [`crate::declarative::declarative_source_find_object_by_string_field`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_find_object_by_string_field`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::declarative::declarative_source_find_object_by_string_field`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_find_object_by_string_field(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_find_object_by_string_field<'a>(
    array_value: &'a Value,
    field_name: &str,
    expected_value: &str,
) -> Option<&'a Value> {
    array_value
        .as_array()?
        .iter()
        .find(|item| item.get(field_name).and_then(Value::as_str) == Some(expected_value))
}

/// Performs declarative source route path to surface path.
///
/// # Parameters
///
/// - `route_path`: Input consumed by [`crate::declarative::declarative_source_route_path_to_surface_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_route_path_to_surface_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::declarative::declarative_source_route_path_to_surface_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_route_path_to_surface_path(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_route_path_to_surface_path(route_path: &str) -> Option<String> {
    if route_path.is_empty() {
        return Some(String::new());
    }
    let mut result = String::with_capacity(route_path.len());
    let chars: Vec<char> = route_path.chars().collect();
    let mut index = 0usize;
    while index < chars.len() {
        if chars[index] == ':' {
            index += 1;
            result.push('{');
            while index < chars.len() && chars[index] != '/' {
                result.push(chars[index]);
                index += 1;
            }
            result.push('}');
            continue;
        }
        result.push(chars[index]);
        index += 1;
    }
    Some(result)
}

/// Performs declarative source copy optional member.
///
/// # Parameters
///
/// - `target_obj`: Input consumed by [`crate::declarative::declarative_source_copy_optional_member`].
/// - `source_obj`: Input consumed by [`crate::declarative::declarative_source_copy_optional_member`].
/// - `key`: Input consumed by [`crate::declarative::declarative_source_copy_optional_member`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::declarative_source_copy_optional_member`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_copy_optional_member(todo!(), todo!(), "key");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_copy_optional_member(
    target_obj: &mut Map<String, Value>,
    source_obj: &Value,
    key: &str,
) -> bool {
    if key.is_empty() {
        return false;
    }
    if let Some(value) = source_obj.as_object().and_then(|map| map.get(key)) {
        target_obj.insert(key.to_owned(), value.clone());
    }
    true
}

/// Performs declarative source array has string.
///
/// # Parameters
///
/// - `array_value`: Input consumed by [`crate::declarative::declarative_source_array_has_string`].
/// - `expected_value`: Input consumed by [`crate::declarative::declarative_source_array_has_string`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::declarative_source_array_has_string`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::declarative::declarative_source_array_has_string`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_array_has_string(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_array_has_string(array_value: &Value, expected_value: &str) -> bool {
    !expected_value.is_empty()
        && array_value.as_array().is_some_and(|items| {
            items
                .iter()
                .any(|item| item.as_str() == Some(expected_value))
        })
}

/// Performs API prefixed route path.
///
/// # Parameters
///
/// - `route_path`: Input consumed by [`crate::declarative::api_prefixed_route_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::api_prefixed_route_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::api_prefixed_route_path(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn api_prefixed_route_path(route_path: &str) -> Option<String> {
    Some(format!("/api{route_path}"))
}

/// Performs declarative source build operation mut.
///
/// # Parameters
///
/// - `method`: Input consumed by [`crate::declarative::declarative_source_build_operation_mut`].
/// - `path`: Input consumed by [`crate::declarative::declarative_source_build_operation_mut`].
/// - `capability`: Input consumed by [`crate::declarative::declarative_source_build_operation_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_build_operation_mut`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_build_operation_mut(todo!(), std::path::Path::new("fixture.json"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_build_operation_mut(
    method: &str,
    path: &str,
    capability: &str,
) -> Option<Value> {
    if method.is_empty() || path.is_empty() || capability.is_empty() {
        return None;
    }
    let surface_path = declarative_source_route_path_to_surface_path(path)?;
    Some(serde_json::json!({
        "method": method,
        "path": surface_path,
        "capability": capability,
    }))
}

/// Performs declarative source build route operation mut.
///
/// # Parameters
///
/// - `route_root`: Input consumed by [`crate::declarative::declarative_source_build_route_operation_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_build_route_operation_mut`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_build_route_operation_mut(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_build_route_operation_mut(route_root: &Value) -> Option<Value> {
    let kind = route_root.get("kind").and_then(Value::as_str)?;
    let path = route_root.get("path").and_then(Value::as_str)?;
    let capability = route_root.get("policy_gate").and_then(Value::as_str)?;
    let method = if kind == "page" { "GET" } else { "POST" };
    declarative_source_build_operation_mut(method, path, capability)
}

/// Performs declarative source identity param.
///
/// # Parameters
///
/// - `edit_path`: Input consumed by [`crate::declarative::declarative_source_identity_param`].
/// - `context_param`: Input consumed by [`crate::declarative::declarative_source_identity_param`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_identity_param`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_identity_param(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_identity_param(
    edit_path: &str,
    context_param: Option<&str>,
) -> Option<String> {
    if edit_path.is_empty() {
        return None;
    }
    let mut result = None;
    let bytes = edit_path.as_bytes();
    let mut index = 0usize;
    while index < bytes.len() {
        if bytes[index] != b':' {
            index += 1;
            continue;
        }
        let start = index + 1;
        let mut end = start;
        while end < bytes.len() && bytes[end] != b'/' {
            end += 1;
        }
        if end > start {
            let candidate = &edit_path[start..end];
            if context_param != Some(candidate) {
                result = Some(candidate.to_owned());
            }
        }
        index = end;
    }
    result
}

/// Converts an identifier into the human-readable label used by generated surfaces.
///
/// # Parameters
///
/// - `identifier`: Input consumed by [`crate::declarative::declarative_source_label`].
/// - `title_case`: Input consumed by [`crate::declarative::declarative_source_label`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::declarative::declarative_source_label`].
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::declarative::declarative_source_label`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_label(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_label(identifier: &str, title_case: bool) -> String {
    let mut next_word = true;
    identifier
        .chars()
        .map(|ch| {
            let mut out = if ch == '_' { ' ' } else { ch };
            if title_case && next_word && out.is_ascii_lowercase() {
                out = out.to_ascii_uppercase();
            }
            next_word = out == ' ';
            out
        })
        .collect()
}

/// Returns the default item title field.
///
/// # Parameters
///
/// - `entity_fields`: Input consumed by [`crate::declarative::default_item_title_field`].
/// - `identity_field`: Input consumed by [`crate::declarative::default_item_title_field`].
/// - `scope_field`: Input consumed by [`crate::declarative::default_item_title_field`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::default_item_title_field`] can produce a value and [`None`] otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::declarative::default_item_title_field`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::default_item_title_field(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn default_item_title_field(
    entity_fields: &Value,
    identity_field: Option<&str>,
    scope_field: Option<&str>,
) -> Option<String> {
    let preferred = ["name", "title", "label", "slug", "day_of_week"];
    let fields = entity_fields.as_array()?;
    for candidate in preferred {
        if fields
            .iter()
            .any(|item| item.get("field_id").and_then(Value::as_str) == Some(candidate))
        {
            return Some(candidate.to_owned());
        }
    }
    for item in fields {
        let Some(field_id) = item.get("field_id").and_then(Value::as_str) else {
            continue;
        };
        if Some(field_id) == identity_field || Some(field_id) == scope_field {
            continue;
        }
        return Some(field_id.to_owned());
    }
    Some(identity_field.unwrap_or("id").to_owned())
}

/// Performs declarative source default list columns mut.
///
/// # Parameters
///
/// - `response_fields`: Input consumed by [`crate::declarative::declarative_source_default_list_columns_mut`].
/// - `identity_field`: Input consumed by [`crate::declarative::declarative_source_default_list_columns_mut`].
/// - `scope_field`: Input consumed by [`crate::declarative::declarative_source_default_list_columns_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_default_list_columns_mut`] 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::declarative::declarative_source_default_list_columns_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_default_list_columns_mut(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_default_list_columns_mut(
    response_fields: &Value,
    identity_field: Option<&str>,
    scope_field: Option<&str>,
) -> Option<Value> {
    let fields = response_fields.as_array()?;
    let mut columns = Vec::new();
    for item in fields {
        let Some(field_name) = item.as_str() else {
            continue;
        };
        if Some(field_name) == identity_field || Some(field_name) == scope_field {
            continue;
        }
        columns.push(serde_json::json!({
            "field": field_name,
            "label": declarative_source_label(field_name, true),
        }));
        if columns.len() >= 3 {
            break;
        }
    }
    Some(Value::Array(columns))
}

/// Performs declarative source default list columns from form mut.
///
/// # Parameters
///
/// - `form_fields`: Input consumed by [`crate::declarative::declarative_source_default_list_columns_from_form_mut`].
/// - `relation_inputs`: Input consumed by [`crate::declarative::declarative_source_default_list_columns_from_form_mut`].
/// - `identity_field`: Input consumed by [`crate::declarative::declarative_source_default_list_columns_from_form_mut`].
/// - `scope_field`: Input consumed by [`crate::declarative::declarative_source_default_list_columns_from_form_mut`].
/// - `soft_delete_field`: Input consumed by [`crate::declarative::declarative_source_default_list_columns_from_form_mut`].
/// - `auto_sequence_field`: Input consumed by [`crate::declarative::declarative_source_default_list_columns_from_form_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_default_list_columns_from_form_mut`] 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::declarative::declarative_source_default_list_columns_from_form_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_default_list_columns_from_form_mut(todo!(), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_default_list_columns_from_form_mut(
    form_fields: Option<&Value>,
    relation_inputs: Option<&Value>,
    identity_field: Option<&str>,
    scope_field: Option<&str>,
    soft_delete_field: Option<&str>,
    auto_sequence_field: Option<&str>,
) -> Option<Value> {
    let mut columns = Vec::new();
    if let Some(fields) = form_fields.and_then(Value::as_array) {
        for item in fields {
            let Some(field_name) = item.get("field_id").and_then(Value::as_str) else {
                continue;
            };
            if Some(field_name) == identity_field || Some(field_name) == scope_field {
                continue;
            }
            columns.push(serde_json::json!({
                "field": field_name,
                "label": declarative_source_label(field_name, true),
            }));
            if columns.len() >= 3 {
                return Some(Value::Array(columns));
            }
        }
    }
    if let Some(field_name) = auto_sequence_field.filter(|value| !value.is_empty())
        && columns.len() < 3
    {
        columns.push(serde_json::json!({
            "field": field_name,
            "label": declarative_source_label(field_name, true),
        }));
        if columns.len() >= 3 {
            return Some(Value::Array(columns));
        }
    }
    if let Some(field_name) = soft_delete_field.filter(|value| !value.is_empty())
        && columns.len() < 3
    {
        columns.push(serde_json::json!({
            "field": field_name,
            "label": declarative_source_label(field_name, true),
        }));
        if columns.len() >= 3 {
            return Some(Value::Array(columns));
        }
    }
    if let Some(inputs) = relation_inputs.and_then(Value::as_array) {
        for item in inputs {
            let Some(field_name) = item.get("field").and_then(Value::as_str) else {
                continue;
            };
            columns.push(serde_json::json!({
                "field": field_name,
                "label": declarative_source_label(field_name, true),
            }));
            if columns.len() >= 3 {
                break;
            }
        }
    }
    Some(Value::Array(columns))
}

/// Performs declarative source default context binding mut.
///
/// # Parameters
///
/// - `scope_field`: Input consumed by [`crate::declarative::declarative_source_default_context_binding_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_default_context_binding_mut`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_default_context_binding_mut(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_default_context_binding_mut(scope_field: Option<&str>) -> Option<Value> {
    if scope_field != Some("business_id") {
        return None;
    }
    Some(serde_json::json!({
        "state_collection": "businesses",
        "param": "business_slug",
        "match_field": "slug",
        "context_id_field": "id",
        "context_label_field": "name",
        "tenant_collection": "tenants",
        "tenant_match_field": "source_business_id",
        "tenant_match_from_context_field": "id",
    }))
}

/// Performs declarative source derived defaults mut.
///
/// # Parameters
///
/// - `form_fields`: Input consumed by [`crate::declarative::declarative_source_derived_defaults_mut`].
/// - `relation_inputs`: Input consumed by [`crate::declarative::declarative_source_derived_defaults_mut`].
/// - `soft_delete_field`: Input consumed by [`crate::declarative::declarative_source_derived_defaults_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_derived_defaults_mut`] 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::declarative::declarative_source_derived_defaults_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_derived_defaults_mut(todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_derived_defaults_mut(
    form_fields: Option<&Value>,
    relation_inputs: Option<&Value>,
    soft_delete_field: Option<&str>,
) -> Option<Value> {
    let mut defaults = Map::new();
    if let Some(fields) = form_fields.and_then(Value::as_array) {
        for item in fields {
            let Some(field_name) = item.get("field_id").and_then(Value::as_str) else {
                continue;
            };
            let widget = item.get("widget").and_then(Value::as_str);
            let required = item
                .get("required")
                .and_then(Value::as_bool)
                .unwrap_or(false);
            if matches!(widget, Some("textarea" | "text" | "email" | "password")) {
                defaults.insert(field_name.to_owned(), Value::String(String::new()));
                continue;
            }
            if required {
                continue;
            }
        }
    }
    if let Some(soft_delete_field) = soft_delete_field.filter(|value| !value.is_empty()) {
        defaults.insert(soft_delete_field.to_owned(), Value::Bool(true));
    }
    if let Some(inputs) = relation_inputs.and_then(Value::as_array) {
        for item in inputs {
            if let Some(field_name) = item.get("field").and_then(Value::as_str)
                && !field_name.is_empty()
            {
                defaults.insert(field_name.to_owned(), Value::Array(Vec::new()));
            }
        }
    }
    Some(Value::Object(defaults))
}

/// Performs declarative source derived audit events mut.
///
/// # Parameters
///
/// - `entity_id`: Input consumed by [`crate::declarative::declarative_source_derived_audit_events_mut`].
/// - `hard_delete`: Input consumed by [`crate::declarative::declarative_source_derived_audit_events_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_derived_audit_events_mut`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_derived_audit_events_mut("entity", todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_derived_audit_events_mut(
    entity_id: &str,
    hard_delete: bool,
) -> Option<Value> {
    if entity_id.is_empty() {
        return None;
    }
    Some(serde_json::json!({
        "create": format!("generated_{entity_id}_created"),
        "update": format!("generated_{entity_id}_updated"),
        "delete": if hard_delete {
            format!("generated_{entity_id}_deleted")
        } else {
            format!("generated_{entity_id}_deactivated")
        },
    }))
}

const MAX_DECLARATIVE_FILE_BYTES: u64 = 16 * 1024 * 1024;
const MAX_DECLARATIVE_FILES: usize = 4096;

/// Builds a safe relative path.
fn safe_relative_path(text: &str) -> Option<&Path> {
    let path = Path::new(text);
    if text.is_empty()
        || path.is_absolute()
        || path.components().any(|component| {
            matches!(
                component,
                std::path::Component::ParentDir
                    | std::path::Component::RootDir
                    | std::path::Component::Prefix(_)
            )
        })
    {
        return None;
    }
    Some(path)
}

/// Reads JSON or YAML.
fn read_json_or_yaml(path: &Path) -> Option<Value> {
    let metadata = fs::metadata(path).ok()?;
    if !metadata.is_file() || metadata.len() > MAX_DECLARATIVE_FILE_BYTES {
        return None;
    }
    let text = fs::read_to_string(path).ok()?;
    if path.extension().and_then(|value| value.to_str()) == Some("yml")
        || path.extension().and_then(|value| value.to_str()) == Some("yaml")
    {
        pharos_runtime_core::yaml::parse_yaml_text(&text)
    } else {
        serde_json::from_str(&text).ok()
    }
}

/// Retains exact scalar declaration locations for generated JSON diagnostics.
fn attach_yaml_source_map(value: &mut Value, text: &str, source_path: &Path) -> Option<()> {
    let object = value.as_object_mut()?;
    let mut locations = Map::new();
    for (index, line) in text.lines().enumerate() {
        let trimmed = line.trim_start().trim_start_matches("- ");
        let Some((key, raw_value)) = trimmed.split_once(':') else {
            continue;
        };
        let scalar = raw_value.trim().trim_matches(['\'', '"']);
        if scalar.is_empty()
            || !matches!(
                key.trim(),
                "route_id"
                    | "action_id"
                    | "entity_id"
                    | "form_id"
                    | "workflow_id"
                    | "adapter_id"
                    | "page_id"
            )
        {
            continue;
        }
        let column = line.find(key.trim()).unwrap_or(0) + 1;
        locations.insert(
            format!("{}:{scalar}", key.trim()),
            serde_json::json!({"line": index + 1, "column": column}),
        );
    }
    object.insert(
        "__pharos_source".to_owned(),
        serde_json::json!({
            "path": source_path.to_string_lossy(),
            "locations": locations,
        }),
    );
    Some(())
}

/// Builds a safe path to one framework-owned contract file.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::declarative::declarative_source_framework_path`].
/// - `file_name`: Input consumed by [`crate::declarative::declarative_source_framework_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_framework_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_framework_path(std::path::Path::new("build/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_framework_path(artifact_dir: &Path, file_name: &str) -> Option<PathBuf> {
    let relative = safe_relative_path(file_name)?;
    Some(artifact_dir.join("data/contracts").join(relative))
}

/// Reads framework contract.
fn read_framework_contract(artifact_dir: &Path, file_name: &str) -> Option<Value> {
    let path = declarative_source_framework_path(artifact_dir, file_name)?;
    read_json_or_yaml(&path)
}

/// Resolves a dot-separated object or array path without creating intermediate values.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::declarative::declarative_source_resolve_dotted_path`].
/// - `dotted_path`: Input consumed by [`crate::declarative::declarative_source_resolve_dotted_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_resolve_dotted_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::declarative::declarative_source_resolve_dotted_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_resolve_dotted_path(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_resolve_dotted_path<'a>(
    root: &'a Value,
    dotted_path: &str,
) -> Option<&'a Value> {
    if dotted_path.is_empty() {
        return None;
    }
    dotted_path.split('.').try_fold(root, |current, segment| {
        if segment.is_empty() {
            None
        } else if let Ok(index) = segment.parse::<usize>() {
            current.as_array()?.get(index)
        } else {
            current.as_object()?.get(segment)
        }
    })
}

/// Loads a bounded framework contract reference such as `fields.yml#entity.fields`.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::declarative::declarative_source_load_ref_target`].
/// - `ref_text`: Input consumed by [`crate::declarative::declarative_source_load_ref_target`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_load_ref_target`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_load_ref_target(std::path::Path::new("build/dev_docs"), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_load_ref_target(artifact_dir: &Path, ref_text: &str) -> Option<Value> {
    let (file_name, dotted_path) = ref_text.split_once('#')?;
    let file_name = if file_name.ends_with(".json") {
        file_name.to_owned()
    } else {
        let stem = file_name
            .strip_suffix(".yml")
            .or_else(|| file_name.strip_suffix(".yaml"))
            .unwrap_or(file_name);
        format!("{stem}.json")
    };
    let root = read_framework_contract(artifact_dir, &file_name)?;
    Some(declarative_source_resolve_dotted_path(&root, dotted_path)?.clone())
}

/// Returns whether the YAML app manifest exists at an app root.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::declarative::declarative_source_has_yaml_manifest`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::declarative_source_has_yaml_manifest`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_has_yaml_manifest(std::path::Path::new("apps/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_has_yaml_manifest(app_root: &Path) -> bool {
    app_root.join("pharos.app.yml").is_file()
}

/// Resolves the source manifest-selected database contract for scoped compiler policy.
fn database_authoring_path(root: &Path) -> Option<PathBuf> {
    let manifest = pharos_runtime_core::yaml::parse_yaml_file(&root.join("pharos.app.yml"))?;
    let selected = manifest.pointer("/database/migration_contract")?.as_str()?;
    let relative = Path::new(selected);
    if !relative
        .components()
        .all(|component| matches!(component, std::path::Component::Normal(_)))
    {
        return None;
    }
    Some(root.join(relative))
}

/// Compiles YAML matches in directory inner.
fn compile_yaml_matches_in_directory_inner(
    root: &Path,
    dir_path: &Path,
    yaml_suffix: &str,
    depth: usize,
    count: &mut usize,
    database_path: Option<&Path>,
) -> i32 {
    if depth > 64 {
        return 69;
    }
    let Ok(entries) = fs::read_dir(dir_path) else {
        return 0;
    };
    for entry in entries {
        let Ok(entry) = entry else {
            return 69;
        };
        let path = entry.path();
        if path.is_dir() {
            let code = compile_yaml_matches_in_directory_inner(
                root,
                &path,
                yaml_suffix,
                depth + 1,
                count,
                database_path,
            );
            if code != 0 {
                return code;
            }
            continue;
        }
        let Some(name) = path.file_name().and_then(|value| value.to_str()) else {
            continue;
        };
        let database_source = database_path == Some(path.as_path());
        if !name.ends_with(yaml_suffix)
            && !(yaml_suffix == ".yml" && database_source && name.ends_with(".yaml"))
        {
            continue;
        }
        *count = count.saturating_add(1);
        if *count > MAX_DECLARATIVE_FILES {
            return 69;
        }
        let parsed = if database_source {
            crate::database::compile_file(&path).ok()
        } else {
            read_json_or_yaml(&path)
        };
        let Some(mut value) = parsed else {
            return 69;
        };
        let Ok(yaml_text) = fs::read_to_string(&path) else {
            return 69;
        };
        let relative_source = path.strip_prefix(root).unwrap_or(&path);
        if !database_source
            && attach_yaml_source_map(&mut value, &yaml_text, relative_source).is_none()
        {
            return 69;
        }
        let output = path.with_extension("json");
        let Ok(text) = serde_json::to_string_pretty(&value) else {
            return 69;
        };
        if database_source && text.len() > 8 * 1024 * 1024 {
            return 69;
        }
        if pharos_runtime_core::fs::write_binary_file(&output, text.as_bytes(), 0o644).is_err() {
            return 69;
        }
    }
    0
}

/// Compiles matching YAML files to sibling JSON artifacts without invoking a toolchain.
///
/// # Parameters
///
/// - `dir_path`: Input consumed by [`crate::declarative::compile_yaml_matches_in_directory`].
/// - `yaml_suffix`: Input consumed by [`crate::declarative::compile_yaml_matches_in_directory`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::declarative::compile_yaml_matches_in_directory`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::compile_yaml_matches_in_directory(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn compile_yaml_matches_in_directory(dir_path: &Path, yaml_suffix: &str) -> i32 {
    if dir_path.as_os_str().is_empty() || yaml_suffix.is_empty() {
        return 69;
    }
    let mut count = 0;
    let database_path = database_authoring_path(dir_path);
    let manifest = if dir_path.join("pharos.app.yml").is_file() {
        let Some(manifest) =
            pharos_runtime_core::yaml::parse_yaml_file(&dir_path.join("pharos.app.yml"))
        else {
            return 69;
        };
        Some(manifest)
    } else {
        None
    };
    if yaml_suffix == ".yml"
        && manifest
            .as_ref()
            .is_some_and(|value| value.pointer("/database/migration_contract").is_some())
        && database_path.as_ref().is_none_or(|path| {
            !matches!(
                path.extension().and_then(|value| value.to_str()),
                Some("json" | "yml" | "yaml")
            ) || !fs::symlink_metadata(path).is_ok_and(|meta| meta.is_file())
        })
    {
        return 69;
    }
    let status = compile_yaml_matches_in_directory_inner(
        dir_path,
        dir_path,
        yaml_suffix,
        0,
        &mut count,
        database_path.as_deref(),
    );
    if status != 0 || yaml_suffix != ".yml" {
        return status;
    }
    if let Some(path) = database_path {
        let Some(app_id) = manifest
            .as_ref()
            .and_then(|value| value.get("app_id"))
            .and_then(Value::as_str)
        else {
            return 69;
        };
        if pharos_runtime_database::contract::load_contract(&path.with_extension("json"), app_id)
            .is_err()
        {
            return 69;
        }
    }
    0
}

/// Performs declarative source compile pages in directory.
///
/// # Parameters
///
/// - `dir_path`: Input consumed by [`crate::declarative::declarative_source_compile_pages_in_directory`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::declarative::declarative_source_compile_pages_in_directory`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_compile_pages_in_directory(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_compile_pages_in_directory(dir_path: &Path) -> i32 {
    compile_yaml_matches_in_directory(dir_path, ".page.yml")
}

/// Performs declarative source compile fixtures in directory.
///
/// # Parameters
///
/// - `dir_path`: Input consumed by [`crate::declarative::declarative_source_compile_fixtures_in_directory`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::declarative::declarative_source_compile_fixtures_in_directory`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_compile_fixtures_in_directory(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_compile_fixtures_in_directory(dir_path: &Path) -> i32 {
    compile_yaml_matches_in_directory(dir_path, ".yml")
}

/// Normalizes compiled reference text.
fn normalize_compiled_reference_text(root: &Path, text: &str) -> Option<String> {
    let (path_text, fragment) = text.split_once('#').unwrap_or((text, ""));
    let stem = path_text
        .strip_suffix(".yml")
        .or_else(|| path_text.strip_suffix(".yaml"))?;
    let json_path = root.join(format!("{stem}.json"));
    if !json_path.is_file() {
        return None;
    }
    Some(if fragment.is_empty() {
        format!("{stem}.json")
    } else {
        format!("{stem}.json#{fragment}")
    })
}

/// Normalizes compiled JSON value.
fn normalize_compiled_json_value(root: &Path, value: &mut Value) {
    match value {
        Value::Array(items) => {
            for item in items {
                normalize_compiled_json_value(root, item);
            }
        }
        Value::Object(fields) => {
            for item in fields.values_mut() {
                normalize_compiled_json_value(root, item);
            }
        }
        Value::String(text) => {
            if let Some(normalized) = normalize_compiled_reference_text(root, text) {
                *text = normalized;
            }
        }
        Value::Null | Value::Bool(_) | Value::Number(_) => {}
    }
}

/// Normalizes compiled JSON references inner.
fn normalize_compiled_json_references_inner(root: &Path, dir: &Path, depth: usize) -> i32 {
    if depth > 64 {
        return 69;
    }
    let Ok(entries) = fs::read_dir(dir) else {
        return 69;
    };
    for entry in entries {
        let Ok(entry) = entry else {
            return 69;
        };
        let path = entry.path();
        let Ok(metadata) = fs::symlink_metadata(&path) else {
            return 69;
        };
        if metadata.file_type().is_symlink() {
            return 78;
        }
        if metadata.is_dir() {
            let code = normalize_compiled_json_references_inner(root, &path, depth + 1);
            if code != 0 {
                return code;
            }
            continue;
        }
        if !metadata.is_file() || path.extension().and_then(|value| value.to_str()) != Some("json")
        {
            continue;
        }
        let is_schema_surface = path
            .file_name()
            .and_then(|value| value.to_str())
            .is_some_and(|value| value.ends_with(".schema.json"))
            || path
                .parent()
                .and_then(Path::file_name)
                .and_then(|value| value.to_str())
                .is_some_and(|value| value == "schema");
        if is_schema_surface
            || database_authoring_path(root)
                .is_some_and(|source| source.with_extension("json") == path)
        {
            continue;
        }
        let Ok(text) = fs::read_to_string(&path) else {
            return 69;
        };
        let Ok(mut value) = serde_json::from_str::<Value>(&text) else {
            return 69;
        };
        let reference_root = path.parent().unwrap_or(root);
        normalize_compiled_json_value(reference_root, &mut value);
        let Ok(normalized) = serde_json::to_string_pretty(&value) else {
            return 75;
        };
        if pharos_runtime_core::fs::write_file_within(root, &path, normalized.as_bytes(), 0o644)
            .is_err()
        {
            return 69;
        }
    }
    0
}

/// Rewrites compiled YAML references to sibling JSON artifacts in a deployment tree.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::declarative::normalize_compiled_json_references`].
///
/// # Returns
///
/// Returns the computed value produced by [`crate::declarative::normalize_compiled_json_references`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::normalize_compiled_json_references(std::path::Path::new("."));
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn normalize_compiled_json_references(root: &Path) -> i32 {
    if root.as_os_str().is_empty() || !root.is_dir() {
        return 64;
    }
    normalize_compiled_json_references_inner(root, root, 0)
}

/// Converts one generated-admin path into its final resource segment.
///
/// # Parameters
///
/// - `manage_path`: Input consumed by [`crate::declarative::declarative_source_path_segment_from_manage_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_path_segment_from_manage_path`] can produce a value and [`None`] otherwise.
///
/// # Panics
///
/// May panic if an internal invariant assumed by [`crate::declarative::declarative_source_path_segment_from_manage_path`] is violated.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::declarative::declarative_source_path_segment_from_manage_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_path_segment_from_manage_path(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_path_segment_from_manage_path(manage_path: &str) -> Option<String> {
    let segment = manage_path
        .trim_matches('/')
        .rsplit('/')
        .find(|value| !value.is_empty() && !value.starts_with(':') && !value.starts_with('{'))?;
    Some(segment.to_owned())
}

/// Derives a stable generated-admin collection segment from entity metadata.
///
/// # Parameters
///
/// - `entity_id`: Input consumed by [`crate::declarative::declarative_source_default_path_segment`].
/// - `runtime_collection`: Input consumed by [`crate::declarative::declarative_source_default_path_segment`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_default_path_segment`] 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::declarative::declarative_source_default_path_segment`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_default_path_segment("entity", todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_default_path_segment(
    entity_id: &str,
    runtime_collection: Option<&str>,
) -> Option<String> {
    if let Some(collection) = runtime_collection.filter(|value| !value.is_empty()) {
        if !collection.contains('_') {
            return Some(collection.to_owned());
        }
        if let Some(suffix) = collection
            .rsplit('_')
            .next()
            .filter(|value| !value.is_empty())
        {
            return Some(suffix.to_owned());
        }
    }
    if entity_id.is_empty() {
        return None;
    }
    if let Some(suffix) = entity_id
        .rsplit('_')
        .next()
        .filter(|value| !value.is_empty())
        && suffix != entity_id
    {
        return Some(suffix.to_owned());
    }
    Some(if let Some(stem) = entity_id.strip_suffix('y') {
        format!("{stem}ies")
    } else if entity_id.ends_with('s') {
        format!("{entity_id}es")
    } else {
        format!("{entity_id}s")
    })
}

/// Builds one operation path using the route contract's colon-parameter syntax.
///
/// # Parameters
///
/// - `manage_path`: Input consumed by [`crate::declarative::declarative_source_operation_path`].
/// - `api_prefix`: Input consumed by [`crate::declarative::declarative_source_operation_path`].
/// - `identity_param`: Input consumed by [`crate::declarative::declarative_source_operation_path`].
/// - `suffix`: Input consumed by [`crate::declarative::declarative_source_operation_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_operation_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_operation_path(todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_operation_path(
    manage_path: &str,
    api_prefix: bool,
    identity_param: Option<&str>,
    suffix: Option<&str>,
) -> Option<String> {
    if manage_path.is_empty() {
        return None;
    }
    let mut output = String::with_capacity(manage_path.len() + 32);
    if api_prefix {
        output.push_str("/api");
    }
    output.push_str(manage_path);
    if let Some(identity) = identity_param.filter(|value| !value.is_empty()) {
        output.push(':');
        output.push_str(identity);
        output.push('/');
    }
    if let Some(suffix) = suffix {
        output.push_str(suffix);
    }
    Some(output)
}

/// Performs declarative source route path has segment.
///
/// # Parameters
///
/// - `route_path`: Input consumed by [`crate::declarative::declarative_source_route_path_has_segment`].
/// - `path_segment`: Input consumed by [`crate::declarative::declarative_source_route_path_has_segment`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::declarative_source_route_path_has_segment`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::declarative::declarative_source_route_path_has_segment`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_route_path_has_segment(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_route_path_has_segment(route_path: &str, path_segment: &str) -> bool {
    !path_segment.is_empty() && route_path.split('/').any(|segment| segment == path_segment)
}

/// Performs declarative source identity param from surface.
///
/// # Parameters
///
/// - `path_segment`: Input consumed by [`crate::declarative::declarative_source_identity_param_from_surface`].
/// - `entity_id`: Input consumed by [`crate::declarative::declarative_source_identity_param_from_surface`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_identity_param_from_surface`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_identity_param_from_surface(todo!(), "entity");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_identity_param_from_surface(
    path_segment: Option<&str>,
    entity_id: &str,
) -> Option<String> {
    let base = path_segment
        .filter(|value| !value.is_empty())
        .unwrap_or(entity_id);
    if base.is_empty() {
        return None;
    }
    let base = base.strip_suffix('s').unwrap_or(base);
    Some(format!("{base}_id"))
}

/// Performs declarative source runtime collection.
///
/// # Parameters
///
/// - `entity_id`: Input consumed by [`crate::declarative::declarative_source_runtime_collection`].
/// - `table_name`: Input consumed by [`crate::declarative::declarative_source_runtime_collection`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_runtime_collection`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_runtime_collection("entity", todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_runtime_collection(
    entity_id: &str,
    table_name: Option<&str>,
) -> Option<String> {
    if let Some(table) = table_name.filter(|value| !value.is_empty()) {
        if table.contains('_') {
            return Some(table.to_owned());
        }
        if entity_id.is_empty() {
            return Some(table.to_owned());
        }
    }
    declarative_source_default_path_segment(entity_id, None)
}

/// Appends a string to an array unless the same string is already present.
///
/// # Parameters
///
/// - `values`: Input consumed by [`crate::declarative::declarative_source_append_unique_string_mut`].
/// - `value`: Input consumed by [`crate::declarative::declarative_source_append_unique_string_mut`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::declarative_source_append_unique_string_mut`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::declarative::declarative_source_append_unique_string_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_append_unique_string_mut(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_append_unique_string_mut(values: &mut Vec<Value>, value: &str) -> bool {
    if value.is_empty() {
        return false;
    }
    if values.iter().any(|entry| entry.as_str() == Some(value)) {
        return true;
    }
    values.push(Value::String(value.to_owned()));
    true
}

/// Performs declarative source derived response fields mut.
///
/// # Parameters
///
/// - `form_fields`: Input consumed by [`crate::declarative::declarative_source_derived_response_fields_mut`].
/// - `relation_inputs`: Input consumed by [`crate::declarative::declarative_source_derived_response_fields_mut`].
/// - `identity_field`: Input consumed by [`crate::declarative::declarative_source_derived_response_fields_mut`].
/// - `scope_field`: Input consumed by [`crate::declarative::declarative_source_derived_response_fields_mut`].
/// - `soft_delete_field`: Input consumed by [`crate::declarative::declarative_source_derived_response_fields_mut`].
/// - `auto_sequence_field`: Input consumed by [`crate::declarative::declarative_source_derived_response_fields_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_derived_response_fields_mut`] 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::declarative::declarative_source_derived_response_fields_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_derived_response_fields_mut(todo!(), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_derived_response_fields_mut(
    form_fields: Option<&Value>,
    relation_inputs: Option<&Value>,
    identity_field: Option<&str>,
    scope_field: Option<&str>,
    soft_delete_field: Option<&str>,
    auto_sequence_field: Option<&str>,
) -> Option<Value> {
    let mut fields = Vec::new();
    declarative_source_append_unique_string_mut(&mut fields, identity_field.unwrap_or_default());
    declarative_source_append_unique_string_mut(&mut fields, scope_field.unwrap_or_default());
    if let Some(items) = form_fields.and_then(Value::as_array) {
        for item in items {
            declarative_source_append_unique_string_mut(
                &mut fields,
                item.get("field_id")
                    .and_then(Value::as_str)
                    .unwrap_or_default(),
            );
        }
    }
    declarative_source_append_unique_string_mut(
        &mut fields,
        auto_sequence_field.unwrap_or_default(),
    );
    declarative_source_append_unique_string_mut(&mut fields, soft_delete_field.unwrap_or_default());
    if let Some(items) = relation_inputs.and_then(Value::as_array) {
        for item in items {
            declarative_source_append_unique_string_mut(
                &mut fields,
                item.get("field")
                    .and_then(Value::as_str)
                    .unwrap_or_default(),
            );
        }
    }
    Some(Value::Array(fields))
}

/// Finds one form-field declaration by its field id.
///
/// # Parameters
///
/// - `fields`: Input consumed by [`crate::declarative::declarative_source_find_field_decl`].
/// - `field_id`: Input consumed by [`crate::declarative::declarative_source_find_field_decl`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_find_field_decl`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_find_field_decl(todo!(), "field");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_find_field_decl<'a>(
    fields: Option<&'a Value>,
    field_id: &str,
) -> Option<&'a Value> {
    declarative_source_find_object_by_string_field(fields?, "field_id", field_id)
}

/// Performs declarative source option values mut.
///
/// # Parameters
///
/// - `options`: Input consumed by [`crate::declarative::declarative_source_option_values_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_option_values_mut`] 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::declarative::declarative_source_option_values_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_option_values_mut(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_option_values_mut(options: &Value) -> Option<Value> {
    let options = options.as_array()?;
    Some(Value::Array(
        options
            .iter()
            .filter_map(|item| item.get("value").and_then(Value::as_str))
            .filter(|value| !value.is_empty())
            .map(|value| Value::String(value.to_owned()))
            .collect(),
    ))
}

/// Performs declarative source derived filters mut.
///
/// # Parameters
///
/// - `filter_set`: Input consumed by [`crate::declarative::declarative_source_derived_filters_mut`].
/// - `form_fields`: Input consumed by [`crate::declarative::declarative_source_derived_filters_mut`].
/// - `relation_inputs`: Input consumed by [`crate::declarative::declarative_source_derived_filters_mut`].
/// - `scope_field`: Input consumed by [`crate::declarative::declarative_source_derived_filters_mut`].
/// - `soft_delete_field`: Input consumed by [`crate::declarative::declarative_source_derived_filters_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_derived_filters_mut`] 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::declarative::declarative_source_derived_filters_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_derived_filters_mut(todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_derived_filters_mut(
    filter_set: &Value,
    form_fields: Option<&Value>,
    relation_inputs: Option<&Value>,
    scope_field: Option<&str>,
    soft_delete_field: Option<&str>,
) -> Option<Value> {
    let mut filters = Vec::new();
    for field_name in filter_set.as_array()? {
        let field_name = field_name.as_str()?;
        if field_name.is_empty() || scope_field == Some(field_name) {
            continue;
        }
        let relation = relation_inputs
            .and_then(|value| value.as_array())
            .and_then(|items| {
                items
                    .iter()
                    .find(|item| item.get("field").and_then(Value::as_str) == Some(field_name))
            });
        let widget = declarative_source_find_field_decl(form_fields, field_name)
            .and_then(|value| value.get("widget"))
            .and_then(Value::as_str);
        let query = if relation.is_some() && field_name.ends_with("_ids") {
            field_name[..field_name.len() - 1].to_owned()
        } else {
            field_name.to_owned()
        };
        let (match_kind, extra) = if relation.is_some() {
            ("array_contains_integer", Value::Null)
        } else if soft_delete_field == Some(field_name) {
            ("boolean", serde_json::json!(true))
        } else if widget == Some("select")
            && declarative_source_find_field_decl(form_fields, field_name)
                .and_then(|value| value.get("options"))
                .is_some()
        {
            (
                "exact",
                declarative_source_find_field_decl(form_fields, field_name)
                    .and_then(|value| value.get("options"))
                    .cloned()
                    .unwrap_or(Value::Array(Vec::new())),
            )
        } else if widget == Some("checkbox") {
            ("boolean", Value::Null)
        } else {
            ("contains", Value::Null)
        };
        let mut filter = serde_json::Map::new();
        filter.insert("query".to_owned(), Value::String(query));
        filter.insert("field".to_owned(), Value::String(field_name.to_owned()));
        filter.insert("match".to_owned(), Value::String(match_kind.to_owned()));
        if !extra.is_null() {
            if match_kind == "boolean" {
                filter.insert("default".to_owned(), extra);
            } else {
                filter.insert("options".to_owned(), extra);
            }
        }
        filter.insert(
            "label".to_owned(),
            Value::String(declarative_source_label(field_name, true)),
        );
        filters.push(Value::Object(filter));
    }
    Some(Value::Array(filters))
}

/// Performs declarative source derived sorts mut.
///
/// # Parameters
///
/// - `sort_set`: Input consumed by [`crate::declarative::declarative_source_derived_sorts_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_derived_sorts_mut`] 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::declarative::declarative_source_derived_sorts_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_derived_sorts_mut(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_derived_sorts_mut(sort_set: &Value) -> Option<Value> {
    let mut sorts = Vec::new();
    for sort_key in sort_set.as_array()? {
        let sort_key = sort_key.as_str()?;
        if sort_key.is_empty() {
            continue;
        }
        if sort_key == "day_time_asc" {
            sorts.push(serde_json::json!({
                "key": sort_key, "field": "day_of_week", "direction": "asc",
                "type": "weekday", "secondary_field": "start_time", "secondary_type": "string",
                "label": "Day / start time"
            }));
            continue;
        }
        let (field, direction) = if let Some(field) = sort_key.strip_suffix("_desc") {
            (field, "desc")
        } else if let Some(field) = sort_key.strip_suffix("_asc") {
            (field, "asc")
        } else {
            (sort_key, "asc")
        };
        if field.is_empty() {
            continue;
        }
        let kind = if field.contains("time") {
            "string"
        } else if field.contains("order") || field.contains("duration") {
            "number"
        } else {
            "string"
        };
        sorts.push(serde_json::json!({
            "key": sort_key, "field": field, "direction": direction,
            "type": kind, "label": declarative_source_label(field, true)
        }));
    }
    Some(Value::Array(sorts))
}

/// Performs declarative source derived surface uniqueness rules mut.
///
/// # Parameters
///
/// - `uniqueness_rules`: Input consumed by [`crate::declarative::declarative_source_derived_surface_uniqueness_rules_mut`].
/// - `entity_fields`: Input consumed by [`crate::declarative::declarative_source_derived_surface_uniqueness_rules_mut`].
/// - `entity_id`: Input consumed by [`crate::declarative::declarative_source_derived_surface_uniqueness_rules_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_derived_surface_uniqueness_rules_mut`] 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::declarative::declarative_source_derived_surface_uniqueness_rules_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_derived_surface_uniqueness_rules_mut(todo!(), todo!(), "entity");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_derived_surface_uniqueness_rules_mut(
    uniqueness_rules: &Value,
    entity_fields: &Value,
    entity_id: &str,
) -> Option<Value> {
    if entity_id.is_empty() {
        return None;
    }
    let mut rules = Vec::new();
    for rule_text in uniqueness_rules.as_array()? {
        let rule_text = rule_text.as_str()?.trim();
        if rule_text.is_empty() {
            continue;
        }
        let fields: Vec<Value> = rule_text
            .split('+')
            .map(str::trim)
            .filter(|field| !field.is_empty())
            .map(|field| Value::String(field.to_owned()))
            .collect();
        if fields.is_empty() {
            continue;
        }
        let casefold_fields: Vec<Value> = fields
            .iter()
            .filter_map(|field| {
                let name = field.as_str()?;
                (declarative_source_find_field_decl(Some(entity_fields), name)
                    .and_then(|value| value.get("type"))
                    .and_then(Value::as_str)
                    == Some("string"))
                .then(|| Value::String(name.to_owned()))
            })
            .collect();
        let mut rule = serde_json::Map::new();
        rule.insert("fields".to_owned(), Value::Array(fields));
        if !casefold_fields.is_empty() {
            rule.insert("casefold_fields".to_owned(), Value::Array(casefold_fields));
        }
        rule.insert(
            "rule_id".to_owned(),
            Value::String(format!("{entity_id}_unique")),
        );
        rule.insert(
            "message".to_owned(),
            Value::String(format!("{entity_id} must be unique within this scope.")),
        );
        rules.push(Value::Object(rule));
    }
    Some(Value::Array(rules))
}

/// Performs declarative source append surface.
///
/// # Parameters
///
/// - `surfaces`: Input consumed by [`crate::declarative::declarative_source_append_surface`].
/// - `surface_root`: Input consumed by [`crate::declarative::declarative_source_append_surface`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::declarative_source_append_surface`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_append_surface(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_append_surface(surfaces: &mut Vec<Value>, surface_root: Value) -> bool {
    if surfaces.len() >= MAX_DECLARATIVE_FILES {
        return false;
    }
    surfaces.push(surface_root);
    true
}

/// Performs declarative source append generated route mut.
///
/// # Parameters
///
/// - `routes`: Input consumed by [`crate::declarative::declarative_source_append_generated_route_mut`].
/// - `route_id`: Input consumed by [`crate::declarative::declarative_source_append_generated_route_mut`].
/// - `path`: Input consumed by [`crate::declarative::declarative_source_append_generated_route_mut`].
/// - `kind`: Input consumed by [`crate::declarative::declarative_source_append_generated_route_mut`].
/// - `page_or_action_id`: Input consumed by [`crate::declarative::declarative_source_append_generated_route_mut`].
/// - `auth_gate`: Input consumed by [`crate::declarative::declarative_source_append_generated_route_mut`].
/// - `policy_gate`: Input consumed by [`crate::declarative::declarative_source_append_generated_route_mut`].
/// - `layout_id`: Input consumed by [`crate::declarative::declarative_source_append_generated_route_mut`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::declarative_source_append_generated_route_mut`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_append_generated_route_mut(todo!(), todo!(), std::path::Path::new("fixture.json"), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_append_generated_route_mut(
    routes: &mut Vec<Value>,
    route_id: &str,
    path: &str,
    kind: &str,
    page_or_action_id: &str,
    auth_gate: Option<&str>,
    policy_gate: Option<&str>,
    layout_id: Option<&str>,
) -> bool {
    if route_id.is_empty()
        || path.is_empty()
        || page_or_action_id.is_empty()
        || !matches!(kind, "page" | "action")
    {
        return false;
    }
    let mut route = serde_json::Map::new();
    route.insert("route_id".to_owned(), Value::String(route_id.to_owned()));
    route.insert("path".to_owned(), Value::String(path.to_owned()));
    route.insert("kind".to_owned(), Value::String(kind.to_owned()));
    route.insert(
        (if kind == "page" {
            "page_id"
        } else {
            "action_id"
        })
        .to_owned(),
        Value::String(page_or_action_id.to_owned()),
    );
    route.insert(
        "layout_id".to_owned(),
        Value::String(layout_id.unwrap_or("generated_admin_shell").to_owned()),
    );
    route.insert(
        "auth_gate".to_owned(),
        Value::String(auth_gate.unwrap_or("session_required").to_owned()),
    );
    route.insert(
        "policy_gate".to_owned(),
        Value::String(policy_gate.unwrap_or_default().to_owned()),
    );
    route.insert("islands".to_owned(), Value::Array(Vec::new()));
    routes.push(Value::Object(route));
    true
}

/// Performs declarative source generated API request hooks.
fn declarative_source_generated_api_request_hooks() -> Value {
    Value::Array(vec![Value::String("json_body_required".to_owned())])
}

/// Performs declarative source find generated query for entity.
///
/// # Parameters
///
/// - `queries`: Input consumed by [`crate::declarative::declarative_source_find_generated_query_for_entity`].
/// - `entity_id`: Input consumed by [`crate::declarative::declarative_source_find_generated_query_for_entity`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_find_generated_query_for_entity`] 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::declarative::declarative_source_find_generated_query_for_entity`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_find_generated_query_for_entity(todo!(), "entity");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_find_generated_query_for_entity<'a>(
    queries: &'a Value,
    entity_id: &str,
) -> Option<&'a Value> {
    if entity_id.is_empty() {
        return None;
    }
    let items = queries.as_array()?;
    let mut match_value = None;
    for item in items {
        if item.get("entity_id").and_then(Value::as_str) != Some(entity_id) {
            continue;
        }
        if match_value.is_some() {
            return None;
        }
        match_value = Some(item);
    }
    match_value
}

/// Performs declarative source find generated form for entity.
///
/// # Parameters
///
/// - `forms`: Input consumed by [`crate::declarative::declarative_source_find_generated_form_for_entity`].
/// - `entity_id`: Input consumed by [`crate::declarative::declarative_source_find_generated_form_for_entity`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_find_generated_form_for_entity`] 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::declarative::declarative_source_find_generated_form_for_entity`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_find_generated_form_for_entity(todo!(), "entity");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_find_generated_form_for_entity<'a>(
    forms: &'a Value,
    entity_id: &str,
) -> Option<&'a Value> {
    if entity_id.is_empty() {
        return None;
    }
    let items = forms.as_array()?;
    let mut match_value = None;
    for item in items {
        if item.get("entity_id").and_then(Value::as_str) != Some(entity_id) {
            continue;
        }
        if match_value.is_some() {
            return None;
        }
        match_value = Some(item);
    }
    match_value
}

/// Performs declarative source find manage route.
///
/// # Parameters
///
/// - `routes`: Input consumed by [`crate::declarative::declarative_source_find_manage_route`].
/// - `path_segment`: Input consumed by [`crate::declarative::declarative_source_find_manage_route`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_find_manage_route`] 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::declarative::declarative_source_find_manage_route`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_find_manage_route(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_find_manage_route<'a>(
    routes: &'a Value,
    path_segment: &str,
) -> Option<&'a Value> {
    if path_segment.is_empty() {
        return None;
    }
    let items = routes.as_array()?;
    let mut match_value = None;
    for item in items {
        let is_match = item.get("kind").and_then(Value::as_str) == Some("page")
            && item.get("page_id").and_then(Value::as_str) == Some("generated_admin_manage")
            && item
                .get("path")
                .and_then(Value::as_str)
                .is_some_and(|path| declarative_source_route_path_has_segment(path, path_segment));
        if !is_match {
            continue;
        }
        if match_value.is_some() {
            return None;
        }
        match_value = Some(item);
    }
    match_value
}

/// Resolves array.
fn resolve_array(value: Option<&Value>, artifact_dir: &Path) -> Option<Value> {
    match value? {
        Value::Array(_) => value.cloned(),
        Value::String(reference) => declarative_source_load_ref_target(artifact_dir, reference),
        _ => None,
    }
}

/// Copies member.
fn copy_member(target: &mut serde_json::Map<String, Value>, source: &Value, key: &str) {
    if let Some(value) = source.get(key) {
        target.insert(key.to_owned(), value.clone());
    }
}

/// Builds one generated surface from declarative entity, query, form, and route values.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::declarative::declarative_source_build_surface_mut`].
/// - `entity_root`: Input consumed by [`crate::declarative::declarative_source_build_surface_mut`].
/// - `query_root`: Input consumed by [`crate::declarative::declarative_source_build_surface_mut`].
/// - `form_root`: Input consumed by [`crate::declarative::declarative_source_build_surface_mut`].
/// - `manage_route`: Input consumed by [`crate::declarative::declarative_source_build_surface_mut`].
/// - `surface_kind`: Input consumed by [`crate::declarative::declarative_source_build_surface_mut`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_build_surface_mut`] 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::declarative::declarative_source_build_surface_mut`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_build_surface_mut(std::path::Path::new("build/dev_docs"), todo!(), todo!(), todo!(), todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_build_surface_mut(
    artifact_dir: &Path,
    entity_root: &Value,
    query_root: &Value,
    form_root: &Value,
    manage_route: &Value,
    surface_kind: &str,
) -> Option<Value> {
    if !matches!(surface_kind, "generated_admin" | "generated_api") {
        return None;
    }
    let generated = entity_root.get("generated_surfaces")?;
    let requested = if surface_kind == "generated_admin" {
        "admin"
    } else {
        "api"
    };
    if !declarative_source_array_has_string(generated, requested) {
        return None;
    }
    let entity_id = entity_root.get("entity_id")?.as_str()?;
    let query_id = query_root.get("query_id")?.as_str()?;
    let form_id = form_root.get("form_id")?.as_str()?;
    let identity_field = entity_root.get("identity_field")?.as_str()?;
    let scope_field = entity_root.get("scope_field")?.as_str()?;
    let runtime_collection = entity_root
        .get("runtime_collection")
        .and_then(Value::as_str)
        .map(ToOwned::to_owned)
        .or_else(|| {
            declarative_source_runtime_collection(
                entity_id,
                entity_root.get("table").and_then(Value::as_str),
            )
        })?;
    let manage_path = manage_route.get("path")?.as_str()?;
    let path_segment = entity_root
        .get("path_segment")
        .and_then(Value::as_str)
        .filter(|value| !value.is_empty())
        .map(ToOwned::to_owned)
        .or_else(|| declarative_source_path_segment_from_manage_path(manage_path))?;
    let identity_param =
        declarative_source_identity_param_from_surface(Some(&path_segment), entity_id)?;
    let entity_fields = resolve_array(entity_root.get("fields"), artifact_dir)?;
    let form_fields = resolve_array(form_root.get("fields"), artifact_dir)?;
    let relation_inputs = form_root.get("relation_inputs");
    let field_types = {
        let mut types = serde_json::Map::new();
        for field in entity_fields.as_array()? {
            if let (Some(id), Some(kind)) = (
                field.get("field_id").and_then(Value::as_str),
                field.get("type").and_then(Value::as_str),
            ) {
                types.insert(id.to_owned(), Value::String(kind.to_owned()));
            }
        }
        if let Some(inputs) = relation_inputs.and_then(Value::as_array) {
            for input in inputs {
                if let Some(field) = input.get("field").and_then(Value::as_str) {
                    types.insert(field.to_owned(), Value::String("array_integer".to_owned()));
                }
            }
        }
        Value::Object(types)
    };
    let capability = manage_route
        .get("policy_gate")
        .and_then(Value::as_str)
        .unwrap_or("");
    let soft_restore_supported = entity_root
        .get("soft_delete_field")
        .and_then(Value::as_str)
        .is_some_and(|value| !value.is_empty())
        && entity_root.get("delete_strategy").and_then(Value::as_str) != Some("hard");
    let mut operations = if surface_kind == "generated_admin" {
        serde_json::json!({
            "manage": declarative_source_build_operation_mut("GET", manage_path, capability)?,
            "create": declarative_source_build_operation_mut("POST", &declarative_source_operation_path(manage_path, false, None, Some("new/"))?, capability)?,
            "edit": declarative_source_build_operation_mut("GET", &declarative_source_operation_path(manage_path, false, Some(&identity_param), Some("edit/"))?, capability)?,
            "update": declarative_source_build_operation_mut("POST", &declarative_source_operation_path(manage_path, false, Some(&identity_param), Some("edit/"))?, capability)?,
            "delete": declarative_source_build_operation_mut("POST", &declarative_source_operation_path(manage_path, false, Some(&identity_param), Some("delete/"))?, capability)?
        })
    } else {
        serde_json::json!({
            "list": declarative_source_build_operation_mut("GET", &api_prefixed_route_path(manage_path)?, capability)?,
            "schema": declarative_source_build_operation_mut("GET", &declarative_source_operation_path(manage_path, true, None, Some("schema/"))?, capability)?,
            "create": declarative_source_build_operation_mut("POST", &api_prefixed_route_path(manage_path)?, capability)?,
            "update": declarative_source_build_operation_mut("POST", &declarative_source_operation_path(manage_path, true, Some(&identity_param), None)?, capability)?,
            "delete": declarative_source_build_operation_mut("POST", &declarative_source_operation_path(manage_path, true, Some(&identity_param), Some("delete/"))?, capability)?
        })
    };
    if soft_restore_supported && let Some(object) = operations.as_object_mut() {
        let restore_path = declarative_source_operation_path(
            manage_path,
            surface_kind == "generated_api",
            Some(&identity_param),
            Some("restore/"),
        )?;
        object.insert(
            "restore".to_owned(),
            declarative_source_build_operation_mut("POST", &restore_path, capability)?,
        );
    }
    let mut surface = serde_json::Map::new();
    surface.insert(
        "surface_id".to_owned(),
        Value::String(format!("{entity_id}_{surface_kind}")),
    );
    surface.insert(
        "surface_kind".to_owned(),
        Value::String(surface_kind.to_owned()),
    );
    surface.insert("entity_id".to_owned(), Value::String(entity_id.to_owned()));
    surface.insert(
        "entity_collection".to_owned(),
        Value::String(runtime_collection.clone()),
    );
    surface.insert("query_id".to_owned(), Value::String(query_id.to_owned()));
    surface.insert("form_id".to_owned(), Value::String(form_id.to_owned()));
    surface.insert(
        "identity_field".to_owned(),
        Value::String(identity_field.to_owned()),
    );
    surface.insert("identity_param".to_owned(), Value::String(identity_param));
    surface.insert(
        "scope_field".to_owned(),
        Value::String(scope_field.to_owned()),
    );
    surface.insert("field_types".to_owned(), field_types);
    surface.insert("operations".to_owned(), operations);
    if let Some(value) = entity_root.get("context_binding") {
        surface.insert("context_binding".to_owned(), value.clone());
    } else if let Some(value) = declarative_source_default_context_binding_mut(Some(scope_field)) {
        surface.insert("context_binding".to_owned(), value);
    }
    if let Some(value) = query_root.get("response_fields") {
        surface.insert("response_fields".to_owned(), value.clone());
    } else if let Some(value) = declarative_source_derived_response_fields_mut(
        Some(&form_fields),
        relation_inputs,
        Some(identity_field),
        Some(scope_field),
        entity_root.get("soft_delete_field").and_then(Value::as_str),
        entity_root
            .get("auto_sequence_field")
            .and_then(Value::as_str),
    ) {
        surface.insert("response_fields".to_owned(), value);
    }
    if let Some(value) = query_root.get("filters") {
        surface.insert("filters".to_owned(), value.clone());
    } else if let Some(value) = query_root.get("filter_set").and_then(|value| {
        declarative_source_derived_filters_mut(
            value,
            Some(&form_fields),
            relation_inputs,
            Some(scope_field),
            entity_root.get("soft_delete_field").and_then(Value::as_str),
        )
    }) {
        surface.insert("filters".to_owned(), value);
    }
    if let Some(value) = query_root.get("sorts") {
        surface.insert("sorts".to_owned(), value.clone());
    } else if let Some(value) = query_root
        .get("sort_set")
        .and_then(declarative_source_derived_sorts_mut)
    {
        surface.insert("sorts".to_owned(), value);
    }
    if let Some(value) = form_root.get("defaults") {
        surface.insert("defaults".to_owned(), value.clone());
    } else if let Some(value) = declarative_source_derived_defaults_mut(
        Some(&form_fields),
        relation_inputs,
        entity_root.get("soft_delete_field").and_then(Value::as_str),
    ) {
        surface.insert("defaults".to_owned(), value);
    }
    copy_member(&mut surface, form_root, "field_constraints");
    copy_member(&mut surface, form_root, "relation_inputs");
    copy_member(&mut surface, entity_root, "auto_sequence_field");
    copy_member(&mut surface, entity_root, "soft_delete_field");
    copy_member(&mut surface, entity_root, "delete_strategy");
    if let Some(value) = entity_root.get("surface_uniqueness_rules") {
        surface.insert("surface_uniqueness_rules".to_owned(), value.clone());
    } else if let Some(value) = entity_root.get("uniqueness_rules").and_then(|value| {
        declarative_source_derived_surface_uniqueness_rules_mut(value, &entity_fields, entity_id)
    }) {
        surface.insert("surface_uniqueness_rules".to_owned(), value);
    }
    if let Some(value) = entity_root.get("audit_events") {
        surface.insert("audit_events".to_owned(), value.clone());
    } else if let Some(value) = declarative_source_derived_audit_events_mut(
        entity_id,
        entity_root.get("delete_strategy").and_then(Value::as_str) == Some("hard"),
    ) {
        surface.insert("audit_events".to_owned(), value);
    }
    if let Some(value) = surface.get("surface_uniqueness_rules").cloned() {
        surface.insert("uniqueness_rules".to_owned(), value);
    }
    if surface_kind == "generated_admin" {
        let admin_source = manage_route
            .get("admin_surface")
            .and_then(|value| value.as_object());
        let response_fields = surface
            .get("response_fields")
            .unwrap_or(&Value::Array(Vec::new()))
            .clone();
        let mut admin = serde_json::Map::new();
        admin.insert(
            "manage_page_template".to_owned(),
            Value::String("templates/generated_admin/manage.page.json".to_owned()),
        );
        admin.insert(
            "edit_page_template".to_owned(),
            Value::String("templates/generated_admin/edit.page.json".to_owned()),
        );
        admin.insert(
            "list_title".to_owned(),
            Value::String(declarative_source_label(entity_id, true)),
        );
        admin.insert(
            "list_intro".to_owned(),
            Value::String(declarative_source_label(&runtime_collection, true)),
        );
        admin.insert(
            "filter_title".to_owned(),
            Value::String(declarative_source_label(&runtime_collection, true)),
        );
        admin.insert(
            "records_title".to_owned(),
            Value::String(declarative_source_label(&runtime_collection, true)),
        );
        admin.insert(
            "create_title".to_owned(),
            Value::String(declarative_source_label(entity_id, true)),
        );
        admin.insert(
            "create_button_label".to_owned(),
            Value::String("Create".to_owned()),
        );
        admin.insert(
            "save_button_label".to_owned(),
            Value::String("Save".to_owned()),
        );
        admin.insert(
            "empty_state_text".to_owned(),
            Value::String("No records found.".to_owned()),
        );
        admin.insert(
            "item_title_field".to_owned(),
            Value::String(default_item_title_field(
                &entity_fields,
                Some(identity_field),
                Some(scope_field),
            )?),
        );
        admin.insert(
            "list_columns".to_owned(),
            declarative_source_default_list_columns_mut(
                &response_fields,
                Some(identity_field),
                Some(scope_field),
            )?,
        );
        if let Some(source) = admin_source {
            for key in [
                "list_title",
                "list_intro",
                "back_path_template",
                "filter_title",
                "records_title",
                "create_title",
                "create_button_label",
                "save_button_label",
                "empty_state_text",
                "item_title_field",
                "delete_button_label",
                "list_columns",
                "composition",
            ] {
                if let Some(value) = source.get(key) {
                    admin.insert(key.to_owned(), value.clone());
                }
            }
        }
        surface.insert("admin".to_owned(), Value::Object(admin));
    }
    Some(Value::Object(surface))
}

/// Derives and writes the generated surface fixture from framework contract files.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::declarative::declarative_source_derive_generated_surface_fixture`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_derive_generated_surface_fixture`] 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::declarative::declarative_source_derive_generated_surface_fixture`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_derive_generated_surface_fixture(std::path::Path::new("build/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_derive_generated_surface_fixture(artifact_dir: &Path) -> Option<usize> {
    let entities = read_framework_contract(artifact_dir, "entities.json")?
        .get("entities")?
        .clone();
    let queries = read_framework_contract(artifact_dir, "queries.json")?
        .get("queries")?
        .clone();
    let forms = read_framework_contract(artifact_dir, "forms.json")?
        .get("forms")?
        .clone();
    let routes = read_framework_contract(artifact_dir, "routes.json")?
        .get("routes")?
        .clone();
    let mut surfaces = Vec::new();
    for entity in entities.as_array()? {
        let entity_id = entity.get("entity_id").and_then(Value::as_str)?;
        let generated = entity.get("generated_surfaces");
        let generated_admin_requested =
            declarative_source_array_has_string(generated.unwrap_or(&Value::Null), "admin");
        let generated_api_requested =
            declarative_source_array_has_string(generated.unwrap_or(&Value::Null), "api");
        if !generated_admin_requested && !generated_api_requested {
            continue;
        }
        let collection = entity
            .get("runtime_collection")
            .and_then(Value::as_str)
            .or_else(|| entity.get("table").and_then(Value::as_str));
        let segment = entity
            .get("path_segment")
            .and_then(Value::as_str)
            .filter(|value| !value.is_empty())
            .map(ToOwned::to_owned)
            .or_else(|| declarative_source_default_path_segment(entity_id, collection));
        let query = queries
            .as_array()?
            .iter()
            .find(|value| value.get("entity_id").and_then(Value::as_str) == Some(entity_id));
        let form = forms
            .as_array()?
            .iter()
            .find(|value| value.get("entity_id").and_then(Value::as_str) == Some(entity_id));
        let routes_array = routes.as_array()?;
        let route = declarative_source_surface_anchor_route(
            routes_array,
            segment.as_deref(),
            entity_id,
            generated_admin_requested,
        );
        let (Some(query), Some(form), Some(route)) = (query, form, route) else {
            continue;
        };
        for kind in ["generated_api", "generated_admin"] {
            let requested = if kind == "generated_admin" {
                "admin"
            } else {
                "api"
            };
            if declarative_source_array_has_string(generated.unwrap_or(&Value::Null), requested)
                && let Some(surface) = declarative_source_build_surface_mut(
                    artifact_dir,
                    entity,
                    query,
                    form,
                    &route,
                    kind,
                )
            {
                surfaces.push(surface);
            }
        }
    }
    let output =
        serde_json::json!({"fixture_id": "generated_surface_fixture_v1", "surfaces": surfaces});
    let path = artifact_dir.join("data/contracts/generated-surfaces.json");
    if fs::create_dir_all(path.parent()?).is_err()
        || pharos_runtime_core::fs::write_file_within(
            artifact_dir,
            &path,
            serde_json::to_string_pretty(&output).ok()?.as_bytes(),
            0o644,
        )
        .is_err()
    {
        return None;
    }
    Some(output.get("surfaces")?.as_array()?.len())
}

/// Performs declarative source surface path to route path.
///
/// # Parameters
///
/// - `surface_path`: Input consumed by [`crate::declarative::declarative_source_surface_path_to_route_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_surface_path_to_route_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::declarative::declarative_source_surface_path_to_route_path`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_surface_path_to_route_path(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_surface_path_to_route_path(surface_path: &str) -> Option<String> {
    if surface_path.is_empty() {
        return Some(String::new());
    }
    let mut output = String::with_capacity(surface_path.len());
    let mut chars = surface_path.chars().peekable();
    while let Some(character) = chars.next() {
        if character == '{' {
            output.push(':');
            for next in chars.by_ref() {
                if next == '}' {
                    break;
                }
                output.push(next);
            }
        } else {
            output.push(character);
        }
    }
    Some(output)
}

/// Performs declarative source manage path from create route.
fn declarative_source_manage_path_from_create_route(path: &str) -> Option<String> {
    path.strip_suffix("new/").map(ToOwned::to_owned)
}

/// Performs declarative source surface anchor route.
fn declarative_source_surface_anchor_route(
    routes: &[Value],
    segment: Option<&str>,
    entity_id: &str,
    require_generated_admin: bool,
) -> Option<Value> {
    let generated_admin_manage = routes.iter().find(|value| {
        value.get("kind").and_then(Value::as_str) == Some("page")
            && value.get("page_id").and_then(Value::as_str) == Some("generated_admin_manage")
            && segment.is_some_and(|segment| {
                value
                    .get("path")
                    .and_then(Value::as_str)
                    .is_some_and(|path| declarative_source_route_path_has_segment(path, segment))
            })
    });
    if require_generated_admin || generated_admin_manage.is_some() {
        return generated_admin_manage.cloned();
    }
    let create_action_id = format!("create_{entity_id}");
    routes.iter().find_map(|value| {
        if value.get("kind").and_then(Value::as_str) != Some("action")
            || value.get("action_id").and_then(Value::as_str) != Some(create_action_id.as_str())
        {
            return None;
        }
        let mut route = value.clone();
        let manage_path = route
            .get("path")
            .and_then(Value::as_str)
            .and_then(declarative_source_manage_path_from_create_route)?;
        route["path"] = Value::String(manage_path);
        Some(route)
    })
}

/// Derives missing generated-admin child routes and writes the route artifact.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::declarative::declarative_source_derive_generated_admin_routes`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_derive_generated_admin_routes`] 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::declarative::declarative_source_derive_generated_admin_routes`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_derive_generated_admin_routes(std::path::Path::new("build/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_derive_generated_admin_routes(artifact_dir: &Path) -> Option<usize> {
    let root = read_framework_contract(artifact_dir, "routes.json")?;
    let surfaces = read_framework_contract(artifact_dir, "generated-surfaces.json")?;
    let mut routes = root.get("routes")?.as_array()?.to_vec();
    let mut added = 0usize;
    for surface in surfaces.get("surfaces")?.as_array()? {
        if surface.get("surface_kind").and_then(Value::as_str) != Some("generated_admin") {
            continue;
        }
        let operations = surface.get("operations")?;
        let manage_path = operations.get("manage")?.get("path")?.as_str()?;
        let manage_route_path = declarative_source_surface_path_to_route_path(manage_path)?;
        let manage = routes.iter().find(|route| {
            route.get("kind").and_then(Value::as_str) == Some("page")
                && route.get("page_id").and_then(Value::as_str) == Some("generated_admin_manage")
                && route.get("path").and_then(Value::as_str) == Some(manage_route_path.as_str())
        });
        let Some(manage) = manage else {
            continue;
        };
        let prefix = manage
            .get("route_id")
            .and_then(Value::as_str)
            .unwrap_or("generated")
            .strip_suffix("_manage")
            .unwrap_or("generated")
            .to_owned();
        let auth_gate = manage
            .get("auth_gate")
            .and_then(Value::as_str)
            .map(ToOwned::to_owned);
        let policy_gate = manage
            .get("policy_gate")
            .and_then(Value::as_str)
            .map(ToOwned::to_owned);
        let entity_id = surface
            .get("entity_id")
            .and_then(Value::as_str)
            .unwrap_or("entity")
            .to_owned();
        let mut route_specs = vec![
            (
                "create".to_owned(),
                "create".to_owned(),
                "action".to_owned(),
                format!("create_{entity_id}"),
            ),
            (
                "edit".to_owned(),
                "edit".to_owned(),
                "page".to_owned(),
                format!("{entity_id}_edit"),
            ),
            (
                "update".to_owned(),
                "update".to_owned(),
                "action".to_owned(),
                format!("update_{entity_id}"),
            ),
            (
                "delete".to_owned(),
                "delete".to_owned(),
                "action".to_owned(),
                format!("delete_{entity_id}"),
            ),
        ];
        if operations.get("restore").is_some() {
            route_specs.push((
                "restore".to_owned(),
                "restore".to_owned(),
                "action".to_owned(),
                format!("restore_{entity_id}"),
            ));
        }
        for (suffix, operation, kind, id) in route_specs {
            let route_id = format!("{prefix}_{suffix}");
            if routes
                .iter()
                .any(|route| route.get("route_id").and_then(Value::as_str) == Some(&route_id))
            {
                continue;
            }
            let Some(path) = operations
                .get(operation)
                .and_then(|value| value.get("path"))
                .and_then(Value::as_str)
                .and_then(declarative_source_surface_path_to_route_path)
            else {
                continue;
            };
            if declarative_source_append_generated_route_mut(
                &mut routes,
                &route_id,
                &path,
                &kind,
                &id,
                auth_gate.as_deref(),
                policy_gate.as_deref(),
                Some("generated_admin_shell"),
            ) {
                added += 1;
            }
        }
    }
    let mut result = root;
    result["routes"] = Value::Array(routes);
    pharos_runtime_core::fs::write_file_within(
        artifact_dir,
        &artifact_dir.join("data/contracts/routes.json"),
        serde_json::to_string_pretty(&result).ok()?.as_bytes(),
        0o644,
    )
    .ok()?;
    Some(added)
}

/// Derives missing generated-api mutation routes and writes the route artifact.
///
/// # Parameters
///
/// - `artifact_dir`: Input consumed by [`crate::declarative::declarative_source_derive_generated_api_routes`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::declarative_source_derive_generated_api_routes`] 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::declarative::declarative_source_derive_generated_api_routes`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::declarative_source_derive_generated_api_routes(std::path::Path::new("build/dev_docs"));
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn declarative_source_derive_generated_api_routes(artifact_dir: &Path) -> Option<usize> {
    let root = read_framework_contract(artifact_dir, "routes.json")?;
    let surfaces = read_framework_contract(artifact_dir, "generated-surfaces.json")?;
    let mut routes = root.get("routes")?.as_array()?.to_vec();
    let mut added = 0usize;
    for surface in surfaces.get("surfaces")?.as_array()? {
        if surface.get("surface_kind").and_then(Value::as_str) != Some("generated_api") {
            continue;
        }
        let operations = surface.get("operations")?;
        let entity_id = surface
            .get("entity_id")
            .and_then(Value::as_str)
            .unwrap_or("entity")
            .to_owned();
        let policy_gate = operations
            .get("create")
            .and_then(|value| value.get("capability"))
            .and_then(Value::as_str)
            .map(ToOwned::to_owned)
            .or_else(|| {
                operations
                    .as_object()?
                    .values()
                    .find_map(|value| value.get("capability").and_then(Value::as_str))
                    .map(ToOwned::to_owned)
            });
        let auth_gate = Some("session_required");
        let mut route_specs = vec![
            (
                "api_create".to_owned(),
                "create".to_owned(),
                format!("create_{entity_id}"),
            ),
            (
                "api_update".to_owned(),
                "update".to_owned(),
                format!("update_{entity_id}"),
            ),
            (
                "api_delete".to_owned(),
                "delete".to_owned(),
                format!("delete_{entity_id}"),
            ),
        ];
        if operations.get("restore").is_some() {
            route_specs.push((
                "api_restore".to_owned(),
                "restore".to_owned(),
                format!("restore_{entity_id}"),
            ));
        }
        for (suffix, operation, action_id) in route_specs {
            let route_id = format!("{entity_id}_{suffix}");
            if routes
                .iter()
                .any(|route| route.get("route_id").and_then(Value::as_str) == Some(&route_id))
            {
                continue;
            }
            let Some(path) = operations
                .get(operation)
                .and_then(|value| value.get("path"))
                .and_then(Value::as_str)
                .and_then(declarative_source_surface_path_to_route_path)
            else {
                continue;
            };
            if declarative_source_append_generated_route_mut(
                &mut routes,
                &route_id,
                &path,
                "action",
                &action_id,
                auth_gate,
                policy_gate.as_deref(),
                Some("generated_admin_shell"),
            ) {
                if let Some(route) = routes.last_mut().and_then(Value::as_object_mut) {
                    route.insert(
                        "request_hooks".to_owned(),
                        declarative_source_generated_api_request_hooks(),
                    );
                }
                added += 1;
            }
        }
    }
    let mut result = root;
    result["routes"] = Value::Array(routes);
    pharos_runtime_core::fs::write_file_within(
        artifact_dir,
        &artifact_dir.join("data/contracts/routes.json"),
        serde_json::to_string_pretty(&result).ok()?.as_bytes(),
        0o644,
    )
    .ok()?;
    Some(added)
}

/// Resolves an app-owned artifact template without falling back to shell commands.
///
/// # Parameters
///
/// - `app_root`: Input consumed by [`crate::declarative::artifact_shared_template_path`].
/// - `relative_path`: Input consumed by [`crate::declarative::artifact_shared_template_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::artifact_shared_template_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::artifact_shared_template_path(std::path::Path::new("apps/dev_docs"), "page");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn artifact_shared_template_path(app_root: &Path, relative_path: &str) -> Option<PathBuf> {
    let relative = safe_relative_path(relative_path)?;
    let candidate = app_root.join("assets").join(relative);
    candidate.is_file().then_some(candidate)
}

const YAML_INCLUDE_MAX_DEPTH: usize = 32;
const YAML_BUFFER_LIMIT: usize = 16 * 1024 * 1024;

/// Appends bounded YAML source text to an output buffer.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::declarative::yaml_buffer_append`].
/// - `text`: Input consumed by [`crate::declarative::yaml_buffer_append`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_buffer_append`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_buffer_append(&mut [], "{}");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_buffer_append(buffer: &mut String, text: &str) -> bool {
    if buffer.len().saturating_add(text.len()) > YAML_BUFFER_LIMIT {
        return false;
    }
    buffer.push_str(text);
    true
}

/// Returns the parent directory of a YAML source file.
///
/// # Parameters
///
/// - `file_path`: Input consumed by [`crate::declarative::yaml_dup_parent_dir`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::yaml_dup_parent_dir`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_dup_parent_dir(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_dup_parent_dir(file_path: &str) -> Option<String> {
    Path::new(file_path)
        .parent()
        .map(|path| path.to_string_lossy().into_owned())
}

/// Resolves a safe include path relative to a YAML source file.
///
/// # Parameters
///
/// - `base_file_path`: Input consumed by [`crate::declarative::yaml_join_relative_path`].
/// - `relative_path`: Input consumed by [`crate::declarative::yaml_join_relative_path`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::yaml_join_relative_path`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_join_relative_path(todo!(), "page");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_join_relative_path(base_file_path: &str, relative_path: &str) -> Option<String> {
    if relative_path.is_empty()
        || Path::new(relative_path).is_absolute()
        || relative_path.contains("..")
    {
        return None;
    }
    Some(
        Path::new(base_file_path)
            .parent()?
            .join(relative_path)
            .to_string_lossy()
            .into_owned(),
    )
}

/// Identifies the supported YAML include token form.
///
/// # Parameters
///
/// - `token`: Input consumed by [`crate::declarative::yaml_token_is_include_path`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_token_is_include_path`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_token_is_include_path(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_token_is_include_path(token: &str) -> bool {
    token.trim().starts_with("!include ") || token.trim().starts_with("include:")
}

/// Parses `!include relative[#section]` into its two components.
///
/// # Parameters
///
/// - `token`: Input consumed by [`crate::declarative::yaml_parse_include_token`].
/// - `Option<String>`: Input consumed by [`crate::declarative::yaml_parse_include_token`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::yaml_parse_include_token`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_parse_include_token(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_parse_include_token(token: &str) -> Option<(String, Option<String>)> {
    if !yaml_token_is_include_path(token) {
        return None;
    }
    let raw = token
        .trim()
        .strip_prefix("!include ")
        .or_else(|| token.trim().strip_prefix("include:"))?
        .trim();
    let (path, section) = raw.split_once('#').map_or((raw, None), |(path, section)| {
        (path, Some(section.to_owned()))
    });
    (!path.is_empty() && !path.contains("..")).then(|| (path.to_owned(), section))
}

/// Detects an include directive on one YAML line.
///
/// # Parameters
///
/// - `line`: Input consumed by [`crate::declarative::yaml_line_is_fields_include`].
/// - `String`: Input consumed by [`crate::declarative::yaml_line_is_fields_include`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::yaml_line_is_fields_include`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_line_is_fields_include(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_line_is_fields_include(line: &str) -> Option<(usize, String)> {
    let indent = line
        .len()
        .saturating_sub(line.trim_start_matches(' ').len());
    let token = line.trim();
    yaml_parse_include_token(token).map(|(path, section)| {
        (
            indent,
            format!(
                "{}{}",
                path,
                section.map(|value| format!("#{value}")).unwrap_or_default()
            ),
        )
    })
}

/// Looks up a dotted section in a compiled YAML JSON value.
///
/// # Parameters
///
/// - `root`: Input consumed by [`crate::declarative::yaml_lookup_include_section_value`].
/// - `section_path`: Input consumed by [`crate::declarative::yaml_lookup_include_section_value`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::yaml_lookup_include_section_value`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_lookup_include_section_value(std::path::Path::new("."), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_lookup_include_section_value<'a>(
    root: &'a Value,
    section_path: &str,
) -> Option<&'a Value> {
    declarative_source_resolve_dotted_path(root, section_path)
}

/// Adds indentation to every line of an included YAML block.
///
/// # Parameters
///
/// - `buffer`: Input consumed by [`crate::declarative::yaml_append_indented_block`].
/// - `indent_prefix`: Input consumed by [`crate::declarative::yaml_append_indented_block`].
/// - `include_text`: Input consumed by [`crate::declarative::yaml_append_indented_block`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_append_indented_block`] holds and `false` otherwise.
///
/// # Performance
///
/// Performance is proportional to the size of the supplied inputs and any parsed or loaded data consumed by [`crate::declarative::yaml_append_indented_block`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_append_indented_block(&mut [], todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_append_indented_block(
    buffer: &mut String,
    indent_prefix: &str,
    include_text: &str,
) -> bool {
    for line in include_text.lines() {
        if !yaml_buffer_append(buffer, indent_prefix)
            || !yaml_buffer_append(buffer, line)
            || !yaml_buffer_append(buffer, "\n")
        {
            return false;
        }
    }
    true
}

/// Performs YAML preprocess includes inner.
fn yaml_preprocess_includes_inner(path: &Path, depth: usize) -> Option<String> {
    if depth > YAML_INCLUDE_MAX_DEPTH {
        return None;
    }
    let text = fs::read_to_string(path).ok()?;
    if text.len() > YAML_BUFFER_LIMIT {
        return None;
    }
    let mut output = String::new();
    for line in text.lines() {
        if let Some((indent, token)) = yaml_line_is_fields_include(line) {
            let (relative, section) = yaml_parse_include_token(&format!("!include {token}"))?;
            let child_path = yaml_join_relative_path(&path.to_string_lossy(), &relative)?;
            let child_text = yaml_preprocess_includes_inner(Path::new(&child_path), depth + 1)?;
            let child_text = if let Some(section) = section {
                let value = yaml_read_as_json(&child_path)?;
                serde_json::to_string_pretty(yaml_lookup_include_section_value(&value, &section)?)
                    .ok()?
            } else {
                child_text
            };
            if !yaml_append_indented_block(&mut output, &" ".repeat(indent), &child_text) {
                return None;
            }
        } else if !yaml_buffer_append(&mut output, line) || !yaml_buffer_append(&mut output, "\n") {
            return None;
        }
    }
    Some(output)
}

/// Preprocesses bounded recursive YAML includes using app-relative paths.
///
/// # Parameters
///
/// - `file_path`: Input consumed by [`crate::declarative::yaml_preprocess_includes_from_file`].
/// - `depth`: Input consumed by [`crate::declarative::yaml_preprocess_includes_from_file`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::yaml_preprocess_includes_from_file`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_preprocess_includes_from_file(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_preprocess_includes_from_file(file_path: &str, depth: usize) -> Option<String> {
    yaml_preprocess_includes_inner(Path::new(file_path), depth)
}

/// Identifies an integer YAML scalar.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::declarative::yaml_scalar_is_integer`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_scalar_is_integer`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_scalar_is_integer("value");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_scalar_is_integer(value: &str) -> bool {
    value.trim().parse::<i64>().is_ok()
}

/// Identifies a finite floating-point YAML scalar.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::declarative::yaml_scalar_is_float`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_scalar_is_float`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_scalar_is_float("value");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_scalar_is_float(value: &str) -> bool {
    value.trim().parse::<f64>().is_ok() && value.trim().contains('.')
}

/// Identifies a YAML boolean scalar.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::declarative::yaml_scalar_is_bool`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_scalar_is_bool`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_scalar_is_bool("value");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_scalar_is_bool(value: &str) -> bool {
    matches!(
        value.trim().to_ascii_lowercase().as_str(),
        "true" | "false" | "yes" | "no" | "on" | "off"
    )
}

/// Identifies a YAML null scalar.
///
/// # Parameters
///
/// - `value`: Input consumed by [`crate::declarative::yaml_scalar_is_null`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_scalar_is_null`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_scalar_is_null("value");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_scalar_is_null(value: &str) -> bool {
    matches!(value.trim().to_ascii_lowercase().as_str(), "null" | "~")
}

/// Identifies the YAML boolean tag.
///
/// # Parameters
///
/// - `tag`: Input consumed by [`crate::declarative::yaml_tag_is_bool`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_tag_is_bool`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_tag_is_bool(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_tag_is_bool(tag: &str) -> bool {
    matches!(tag, "!!bool" | "tag:yaml.org,2002:bool")
}

/// Identifies the YAML floating-point tag.
///
/// # Parameters
///
/// - `tag`: Input consumed by [`crate::declarative::yaml_tag_is_float`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_tag_is_float`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_tag_is_float(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_tag_is_float(tag: &str) -> bool {
    matches!(tag, "!!float" | "tag:yaml.org,2002:float")
}

/// Identifies the YAML integer tag.
///
/// # Parameters
///
/// - `tag`: Input consumed by [`crate::declarative::yaml_tag_is_int`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_tag_is_int`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_tag_is_int(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_tag_is_int(tag: &str) -> bool {
    matches!(tag, "!!int" | "tag:yaml.org,2002:int")
}

/// Identifies the YAML null tag.
///
/// # Parameters
///
/// - `tag`: Input consumed by [`crate::declarative::yaml_tag_is_null`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_tag_is_null`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_tag_is_null(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_tag_is_null(tag: &str) -> bool {
    matches!(tag, "!!null" | "tag:yaml.org,2002:null")
}

/// Identifies the YAML string tag.
///
/// # Parameters
///
/// - `tag`: Input consumed by [`crate::declarative::yaml_tag_is_str`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_tag_is_str`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_tag_is_str(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_tag_is_str(tag: &str) -> bool {
    matches!(tag, "!!str" | "tag:yaml.org,2002:str")
}

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

/// Initializes a YAML compile context.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_compile_context_init`].
///
/// # Returns
///
/// Returns after [`crate::declarative::yaml_compile_context_init`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_compile_context_init(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_compile_context_init(context: &mut YamlCompileContext) {
    context.stack.clear();
    context.root = None;
}

/// Releases a YAML compile context.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_compile_context_free`].
///
/// # Returns
///
/// Returns after [`crate::declarative::yaml_compile_context_free`] applies its in-place effect.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_compile_context_free(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_compile_context_free(context: &mut YamlCompileContext) {
    context.stack.clear();
    context.root = None;
}

/// Pushes a mapping or sequence container.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_compile_push`].
/// - `value`: Input consumed by [`crate::declarative::yaml_compile_push`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_compile_push`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_compile_push(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_compile_push(context: &mut YamlCompileContext, value: Value) -> bool {
    context.stack.push(value);
    true
}

/// Completes and returns the current container.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_compile_pop`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::yaml_compile_pop`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_compile_pop(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_compile_pop(context: &mut YamlCompileContext) -> Option<Value> {
    context.stack.pop()
}

/// Borrows the current compile container.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_compile_peek`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::yaml_compile_peek`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_compile_peek(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_compile_peek(context: &YamlCompileContext) -> Option<&Value> {
    context.stack.last()
}

/// Adds a completed value to the active compile container or root.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_compile_add_value`].
/// - `value`: Input consumed by [`crate::declarative::yaml_compile_add_value`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_compile_add_value`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_compile_add_value(todo!(), "value");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_compile_add_value(context: &mut YamlCompileContext, value: Value) -> bool {
    if let Some(parent) = context.stack.last_mut() {
        match parent {
            Value::Array(items) => items.push(value),
            Value::Object(map) => {
                let key = map.len().to_string();
                map.insert(key, value);
            }
            _ => return false,
        }
    } else {
        context.root = Some(value);
    }
    true
}

/// Starts a YAML mapping container.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_handle_mapping_start`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_handle_mapping_start`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_handle_mapping_start(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_handle_mapping_start(context: &mut YamlCompileContext) -> bool {
    yaml_compile_push(context, Value::Object(Map::new()))
}

/// Ends a YAML mapping container.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_handle_mapping_end`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_handle_mapping_end`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_handle_mapping_end(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_handle_mapping_end(context: &mut YamlCompileContext) -> bool {
    let value = yaml_compile_pop(context);
    value.is_some_and(|value| yaml_compile_add_value(context, value))
}

/// Starts a YAML sequence container.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_handle_sequence_start`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_handle_sequence_start`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_handle_sequence_start(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_handle_sequence_start(context: &mut YamlCompileContext) -> bool {
    yaml_compile_push(context, Value::Array(Vec::new()))
}

/// Ends a YAML sequence container.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_handle_sequence_end`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_handle_sequence_end`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_handle_sequence_end(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_handle_sequence_end(context: &mut YamlCompileContext) -> bool {
    let value = yaml_compile_pop(context);
    value.is_some_and(|value| yaml_compile_add_value(context, value))
}

/// Adds a scalar YAML value using the same scalar rules as saphyr.
///
/// # Parameters
///
/// - `context`: Input consumed by [`crate::declarative::yaml_handle_scalar`].
/// - `scalar`: Input consumed by [`crate::declarative::yaml_handle_scalar`].
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_handle_scalar`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_handle_scalar(todo!(), todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_handle_scalar(context: &mut YamlCompileContext, scalar: &str) -> bool {
    let value = if yaml_scalar_is_null(scalar) {
        Value::Null
    } else if yaml_scalar_is_bool(scalar) {
        Value::Bool(matches!(
            scalar.trim().to_ascii_lowercase().as_str(),
            "true" | "yes" | "on"
        ))
    } else if yaml_scalar_is_integer(scalar) {
        Value::Number(scalar.trim().parse::<i64>().ok().unwrap_or_default().into())
    } else if yaml_scalar_is_float(scalar) {
        serde_json::Number::from_f64(scalar.trim().parse::<f64>().ok().unwrap_or_default())
            .map(Value::Number)
            .unwrap_or_else(|| Value::String(scalar.to_owned()))
    } else {
        Value::String(scalar.to_owned())
    };
    yaml_compile_add_value(context, value)
}

/// Compiles YAML text to one JSON value.
///
/// # Parameters
///
/// - `text`: Input consumed by [`crate::declarative::yaml_compile_to_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::yaml_compile_to_json`] can produce a value and [`None`] otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_compile_to_json("{}");
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_compile_to_json(text: &str) -> Option<Value> {
    pharos_runtime_core::yaml::parse_yaml_text(text)
}

/// Reads and compiles one YAML file to JSON.
///
/// # Returns
///
/// Returns `true` when the condition checked by [`crate::declarative::yaml_compile_enabled`] holds and `false` otherwise.
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_compile_enabled();
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_compile_enabled() -> bool {
    true
}

/// Performs YAML read as JSON.
///
/// # Parameters
///
/// - `file_path`: Input consumed by [`crate::declarative::yaml_read_as_json`].
///
/// # Returns
///
/// Returns [`Some`] when [`crate::declarative::yaml_read_as_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::declarative::yaml_read_as_json`].
///
/// # Examples
///
/// ```rust,ignore
/// let _result = pharos_runtime_compiler::declarative::yaml_read_as_json(todo!());
/// ```
///
/// # Related
///
/// - [`crate::declarative`] for adjacent helpers that share the same runtime surface.
pub fn yaml_read_as_json(file_path: &str) -> Option<Value> {
    let text = yaml_preprocess_includes_from_file(file_path, 0)
        .or_else(|| fs::read_to_string(file_path).ok())?;
    yaml_compile_to_json(&text)
}

#[cfg(test)]
mod tests {
    use super::{
        declarative_source_derive_generated_admin_routes,
        declarative_source_derive_generated_api_routes,
        declarative_source_derive_generated_surface_fixture,
    };
    use std::time::{SystemTime, UNIX_EPOCH};

    /// Performs test root.
    fn test_root(label: &str) -> std::path::PathBuf {
        let nonce = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .expect("clock")
            .as_nanos();
        std::env::temp_dir().join(format!(
            "pharos-declarative-{label}-{}-{nonce}",
            std::process::id()
        ))
    }

    /// Writes write.
    fn write(root: &std::path::Path, relative: &str, content: &str) {
        let path = root.join(relative);
        std::fs::create_dir_all(path.parent().expect("parent")).expect("directories");
        std::fs::write(path, content).expect("fixture");
    }

    #[test]
    /// Performs derives generated admin delete route when missing.
    fn derives_generated_admin_delete_route_when_missing() {
        let root = test_root("generated-admin-routes");
        write(
            &root,
            "data/contracts/routes.json",
            r#"{"contract_version":"1.0","routes":[{"route_id":"service_manage","path":"/businesses/:business_slug/services/","kind":"page","page_id":"generated_admin_manage","layout_id":"generated_admin_shell","auth_gate":"session_required","policy_gate":"manage_services","islands":[]}]} "#,
        );
        write(
            &root,
            "data/contracts/generated-surfaces.json",
            r#"{"fixture_id":"generated_surface_fixture_v1","surfaces":[{"surface_id":"service_generated_admin","surface_kind":"generated_admin","entity_id":"service","operations":{"manage":{"method":"GET","path":"/businesses/{business_slug}/services/","capability":"manage_services"},"create":{"method":"POST","path":"/businesses/{business_slug}/services/new/","capability":"manage_services"},"edit":{"method":"GET","path":"/businesses/{business_slug}/services/{service_id}/edit/","capability":"manage_services"},"update":{"method":"POST","path":"/businesses/{business_slug}/services/{service_id}/edit/","capability":"manage_services"},"delete":{"method":"POST","path":"/businesses/{business_slug}/services/{service_id}/delete/","capability":"manage_services"},"restore":{"method":"POST","path":"/businesses/{business_slug}/services/{service_id}/restore/","capability":"manage_services"}}}]}"#,
        );
        assert_eq!(
            declarative_source_derive_generated_admin_routes(&root),
            Some(5)
        );
        let routes =
            std::fs::read_to_string(root.join("data/contracts/routes.json")).expect("routes");
        assert!(routes.contains("\"route_id\": \"service_delete\""));
        assert!(routes.contains("\"action_id\": \"delete_service\""));
        assert!(routes.contains("\"route_id\": \"service_restore\""));
        assert!(routes.contains("\"action_id\": \"restore_service\""));
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Performs derives generated API mutation routes when missing.
    fn derives_generated_api_mutation_routes_when_missing() {
        let root = test_root("generated-api-routes");
        write(
            &root,
            "data/contracts/routes.json",
            r#"{"contract_version":"1.0","routes":[]}"#,
        );
        write(
            &root,
            "data/contracts/generated-surfaces.json",
            r#"{"fixture_id":"generated_surface_fixture_v1","surfaces":[{"surface_id":"service_generated_api","surface_kind":"generated_api","entity_id":"service","operations":{"list":{"method":"GET","path":"/api/businesses/{business_slug}/services/","capability":"manage_services"},"schema":{"method":"GET","path":"/api/businesses/{business_slug}/services/schema/","capability":"manage_services"},"create":{"method":"POST","path":"/api/businesses/{business_slug}/services/","capability":"manage_services"},"update":{"method":"POST","path":"/api/businesses/{business_slug}/services/{service_id}/","capability":"manage_services"},"delete":{"method":"POST","path":"/api/businesses/{business_slug}/services/{service_id}/delete/","capability":"manage_services"},"restore":{"method":"POST","path":"/api/businesses/{business_slug}/services/{service_id}/restore/","capability":"manage_services"}}}]}"#,
        );
        assert_eq!(
            declarative_source_derive_generated_api_routes(&root),
            Some(4)
        );
        let routes =
            std::fs::read_to_string(root.join("data/contracts/routes.json")).expect("routes");
        assert!(routes.contains("\"route_id\": \"service_api_create\""));
        assert!(routes.contains("\"route_id\": \"service_api_update\""));
        assert!(routes.contains("\"route_id\": \"service_api_delete\""));
        assert!(routes.contains("\"route_id\": \"service_api_restore\""));
        assert!(
            routes.contains("\"path\": \"/api/businesses/:business_slug/services/:service_id/\"")
        );
        assert!(routes.contains("\"action_id\": \"update_service\""));
        assert!(routes.contains("\"action_id\": \"restore_service\""));
        assert!(routes.contains("\"request_hooks\": [\n        \"json_body_required\"\n      ]"));
        std::fs::remove_dir_all(root).expect("cleanup");
    }

    #[test]
    /// Performs derives generated API surface without generated admin anchor.
    fn derives_generated_api_surface_without_generated_admin_anchor() {
        let root = test_root("generated-api-surface-anchor");
        write(
            &root,
            "data/contracts/entities.json",
            r#"{"contract_version":"1.0","entities":[{"entity_id":"technician","table":"technician","identity_field":"id","scope_field":"business_id","generated_surfaces":["form","api","manifest"],"fields":[{"field_id":"id","type":"integer"},{"field_id":"business_id","type":"integer"},{"field_id":"name","type":"string"},{"field_id":"email","type":"string"},{"field_id":"is_active","type":"boolean"}],"soft_delete_field":"is_active"}]}"#,
        );
        write(
            &root,
            "data/contracts/queries.json",
            r#"{"contract_version":"1.0","queries":[{"query_id":"technicians_by_business","entity_id":"technician","filter_set":["business_id","is_active"],"sort_set":["name_asc"]}]}"#,
        );
        write(
            &root,
            "data/contracts/forms.json",
            r#"{"contract_version":"1.0","forms":[{"form_id":"technician_form","entity_id":"technician","fields":[{"field_id":"name","type":"string"},{"field_id":"email","type":"string"}],"submits_action":"create_technician"}]}"#,
        );
        write(
            &root,
            "data/contracts/routes.json",
            r#"{"contract_version":"1.0","routes":[{"route_id":"technician_create","path":"/businesses/:business_slug/technicians/new/","kind":"action","action_id":"create_technician","auth_gate":"session_required","policy_gate":"manage_technicians","islands":[]}]}"#,
        );
        assert_eq!(
            declarative_source_derive_generated_surface_fixture(&root),
            Some(1)
        );
        let surfaces = std::fs::read_to_string(root.join("data/contracts/generated-surfaces.json"))
            .expect("surfaces");
        assert!(surfaces.contains("\"surface_id\": \"technician_generated_api\""));
        assert!(surfaces.contains("\"path\": \"/api/businesses/{business_slug}/technicians/\""));
        assert!(surfaces.contains("\"restore\""));
        assert!(
            surfaces
                .contains("/api/businesses/{business_slug}/technicians/{technician_id}/restore/")
        );
        std::fs::remove_dir_all(root).expect("cleanup");
    }
}