xianyun_core/config/

merge.rs

//! Port of `internal/config/merge.go`: `extends:`/local-override composition,
//! RFC 7386-style deep merge with append-list semantics for a handful of
//! keys, and the `caproni-project.yaml` per-repository fragment machinery.
//!
//! ## Remote HTTP fragment resolution: `ureq` (blocking), not `reqwest`/async
//!
//! The Go original threads a `*http.Client` through `resolveExtends`, doing
//! ordinary blocking HTTP calls — Go's goroutine model makes a blocking call
//! cheap and doesn't force the whole call graph onto a runtime. Every other
//! function in this crate is synchronous (`load_caproni_config` and
//! everything it calls), so introducing an async HTTP client (`reqwest`)
//! here would mean either colouring `load_caproni_config` and its ~15
//! callers `async fn` for the sake of one HTTP call three layers deep, or
//! spinning up a throwaway Tokio runtime inside a sync function just to
//! `.block_on()` an async request — both worse than the alternative.
//! `ureq` (a small, dependency-light blocking HTTP client with its own
//! rustls-backed TLS) keeps `resolve_extends`/`load_caproni_config` fully
//! synchronous, matching the Go original's call shape exactly: a
//! `RemoteFetcher` trait object is threaded through the same call chain the
//! Go original threads `*http.Client` through, with [`UreqFetcher`] as the
//! production implementation.
//!
//! **Testing shape**: `RemoteFetcher` is itself the injection seam
//! `UreqFetcher`'s HTTP logic sits behind, so exercising
//! `resolve_extends`/`fetch_deployer_files` doesn't require a real network
//! call at all — an earlier draft of this module planned a `wiremock`+
//! `tokio` mock-HTTP-server setup (rewriting the `https://`-only scheme
//! check's URL to a real `http://127.0.0.1:<port>` mock address before
//! dispatch, wrapping each test in `tokio::task::spawn_blocking` since
//! `wiremock`'s server is async and this crate's HTTP calls are blocking),
//! but every remote-fragment test in `merge.rs`'s test module instead uses
//! an in-process `FakeFetcher`: an in-memory `HashMap<String, Vec<u8>>`
//! keyed by the exact `https://fake-remote.test/...` URL a test's
//! `caproni.yaml` fixture embeds. This tests the same call-graph behavior
//! (`resolve_extends` dispatching to `RemoteFetcher::fetch`, size-limit and
//! not-found handling, caching) without a real socket, TLS story, or async
//! runtime anywhere in the crate — `wiremock`/`tokio` were dropped from
//! `dev-dependencies` once this was confirmed sufficient.
//!
//! **Caching, scoped down from the Go original**: the Go original threads a
//! `filecache.Cache` (a persistent, on-disk, TTL-based cache with a
//! stale-fallback path) through the same call chain, shared across a whole
//! `caproni` invocation so the same URL is fetched at most once per
//! process. [`UreqFetcher`] reproduces only the "fetched at most once per
//! `UreqFetcher` instance" behavior (an in-memory `HashMap` keyed by URL,
//! populated on first fetch) — no on-disk persistence, no TTL, no
//! stale-fallback. Nothing in this crate's test suite exercises staleness
//! or cross-process caching (`TestLoadCaproniConfig_ExtendsRemoteFragment`'s
//! `"caching"` subtest only asserts that two `load_caproni_config` calls
//! sharing one fetcher instance issue one HTTP request between them), so
//! the full `filecache` port is deferred rather than built against no test
//! that needs it.

use std::io::Read as _;
use std::sync::Mutex;

use serde_json::Value;

use super::errors::ConfigError;

/// Maximum size, in bytes, of a fetched remote fragment or downloaded
/// deployer file. Port of `maxFragmentBytes`.
pub(super) const MAX_FRAGMENT_BYTES: u64 = 10 * 1024 * 1024;

/// The only URL scheme `extends:`/deployer-file remote references accept.
/// Port of `remoteFragmentScheme`.
const REMOTE_FRAGMENT_SCHEME: &str = "https://";

/// A deployer's remote-fragment source URL and the file references the
/// fragment itself declared. `fetch_deployer_files` compares the merged
/// deployer against these values: a field a higher-precedence layer
/// replaced no longer refers to the fragment's location and is left to
/// resolve locally. Port of `remoteElement`.
#[derive(Debug, Clone, Default)]
pub(super) struct RemoteElement {
    pub url: String,
    pub values_file: String,
    pub kustomize_path: String,
}

/// Reports whether `source` is a remote (`https://`) reference. Port of
/// `isRemoteSource`.
pub(super) fn is_remote_source(source: &str) -> bool {
    source.starts_with(REMOTE_FRAGMENT_SCHEME)
}

/// Fetches a fragment or file's raw bytes from a URL. Injected through
/// `resolve_extends`/`load_caproni_config` so tests can substitute a
/// `wiremock`-backed double for the real [`UreqFetcher`]; see this module's
/// doc comment for the full design rationale.
pub trait RemoteFetcher: Send + Sync {
    /// Fetches `url`'s body, enforcing the `MAX_FRAGMENT_BYTES` size limit
    /// and a `200 OK` status. Port of `fetchRemoteFile`.
    fn fetch(&self, url: &str) -> Result<Vec<u8>, ConfigError>;
}

/// The production [`RemoteFetcher`]: a blocking `ureq` GET per URL, with an
/// in-memory fetch-at-most-once-per-instance cache. See this module's doc
/// comment for why `ureq` and why the cache is scoped down from the Go
/// original's persistent `filecache.Cache`.
#[derive(Default)]
pub struct UreqFetcher {
    cache: Mutex<std::collections::HashMap<String, Vec<u8>>>,
}

impl UreqFetcher {
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }
}

impl RemoteFetcher for UreqFetcher {
    fn fetch(&self, url: &str) -> Result<Vec<u8>, ConfigError> {
        if let Some(cached) = self.cache.lock().unwrap().get(url) {
            return Ok(cached.clone());
        }

        let body = fetch_remote_file_via_ureq(url)?;
        self.cache
            .lock()
            .unwrap()
            .insert(url.to_string(), body.clone());
        Ok(body)
    }
}

fn fetch_remote_file_via_ureq(url: &str) -> Result<Vec<u8>, ConfigError> {
    let mut response = ureq::get(url)
        .call()
        .map_err(|err| ConfigError::RemoteFragmentFetch(format!("{url}: {err}")))?;

    if response.status() != 200 {
        return Err(ConfigError::RemoteFragmentFetch(format!(
            "{url}: status {}",
            response.status()
        )));
    }

    // Limit set one byte over MAX_FRAGMENT_BYTES so a response of exactly
    // the limit succeeds (matching Go's `io.LimitReader(resp.Body,
    // maxFragmentBytes+1)`), while a larger response either trips ureq's
    // own `BodyExceedsLimit` mid-read or is caught by the length check
    // below once the (still oversized-by-one) read completes.
    let mut body = Vec::new();
    response
        .body_mut()
        .as_reader()
        .take(MAX_FRAGMENT_BYTES + 1)
        .read_to_end(&mut body)
        .map_err(|err| ConfigError::RemoteFragmentFetch(format!("{url}: {err}")))?;

    if body.len() as u64 > MAX_FRAGMENT_BYTES {
        return Err(ConfigError::RemoteFragmentFetch(format!(
            "{url}: response exceeds {MAX_FRAGMENT_BYTES} bytes"
        )));
    }

    Ok(body)
}

const LIFECYCLE_HOOKS_KEY: &str = "lifecycle_hooks";
const ADDITIONAL_HOSTNAMES_KEY: &str = "additional_hostnames";
const DYNAMIC_OVERRIDES_KEY: &str = "dynamic_overrides";
/// Primary local-override filename; `caproni.local.yaml` is supported as
/// a compatibility alias (see [`resolve_local_override_path`]).
const LOCAL_OVERRIDE_FILENAME: &str = "xianyun.local.yaml";
const LOCAL_OVERRIDE_FILENAME_ALIAS: &str = "caproni.local.yaml";

/// Resolves the local-override path next to `config_path`: `xianyun.
/// local.yaml` if it exists, else the `caproni.local.yaml` compatibility
/// alias, else the primary name (so callers get a consistent path for
/// "no override exists" bookkeeping, matching the pre-aliasing behavior).
fn resolve_local_override_path(config_path: &std::path::Path) -> std::path::PathBuf {
    let dir = config_path
        .parent()
        .unwrap_or_else(|| std::path::Path::new("."));
    let primary = dir.join(LOCAL_OVERRIDE_FILENAME);
    if primary.is_file() {
        return primary;
    }
    let alias = dir.join(LOCAL_OVERRIDE_FILENAME_ALIAS);
    if alias.is_file() {
        return alias;
    }
    primary
}

/// Deep-merges `src` into `dst` (RFC 7386-ish): maps merge recursively, a
/// handful of well-known list keys (`additional_hostnames`,
/// `lifecycle_hooks`, `dynamic_overrides`) append rather than replace, other
/// lists replace wholesale, and an explicit `null` in `src` deletes the key
/// from the result at any depth. `dst` is not modified; the merged result is
/// returned as a new value.
pub fn deep_merge(dst: &Value, src: &Value) -> Value {
    let (Some(dst_map), Some(src_map)) = (dst.as_object(), src.as_object()) else {
        return src.clone();
    };

    let mut result = dst_map.clone();

    for (key, src_val) in src_map {
        // An explicit null overlay deletes the key (no-op if it was absent).
        if src_val.is_null() {
            result.remove(key);
            continue;
        }

        let Some(dst_val) = result.get(key) else {
            result.insert(key.clone(), src_val.clone());
            continue;
        };

        if dst_val.is_object() && src_val.is_object() {
            let merged = deep_merge(dst_val, src_val);
            result.insert(key.clone(), merged);
            continue;
        }

        if matches!(
            key.as_str(),
            LIFECYCLE_HOOKS_KEY | ADDITIONAL_HOSTNAMES_KEY | DYNAMIC_OVERRIDES_KEY
        ) && let (Some(dst_arr), Some(src_arr)) = (dst_val.as_array(), src_val.as_array())
        {
            let mut combined = dst_arr.clone();
            combined.extend(src_arr.clone());
            result.insert(key.clone(), Value::Array(combined));
            continue;
        }

        result.insert(key.clone(), src_val.clone());
    }

    Value::Object(result)
}

/// Reports whether `path` matches the fragment-name convention:
/// `xianyun.yaml`/`caproni.yaml` or `xianyun.<name>.yaml`/
/// `caproni.<name>.yaml`, optionally under subdirectories that do not
/// start with a dot. Port of `fragmentNamePattern`'s regex, hand-rolled
/// to avoid adding a `regex` dependency for one pattern (see `naming.rs`'s
/// precedent, noted in `PORT_NOTES.md`). Recognizes both the primary
/// `xianyun` prefix and the pre-rename `caproni` prefix, so an existing
/// project's `extends:` list naming its fragments `caproni.<name>.yaml`
/// still validates.
fn is_valid_fragment_name(path: &str) -> bool {
    let mut parts: Vec<&str> = path.split('/').collect();
    let Some(filename) = parts.pop() else {
        return false;
    };

    if !is_caproni_fragment_filename(filename, "xianyun")
        && !is_caproni_fragment_filename(filename, "caproni")
    {
        return false;
    }

    parts
        .iter()
        .all(|d| *d == "." || (!d.is_empty() && !d.starts_with('.')))
}

fn is_caproni_fragment_filename(name: &str, prefix: &str) -> bool {
    let Some(rest) = name.strip_prefix(prefix) else {
        return false;
    };

    if rest == ".yaml" {
        return true;
    }

    let Some(mid) = rest.strip_prefix('.') else {
        return false;
    };

    mid.strip_suffix(".yaml")
        .is_some_and(|base| !base.is_empty() && !base.contains('/'))
}

/// Port of `extractVersion`.
fn extract_version(
    cfg: &serde_json::Map<String, Value>,
    fallback: i64,
) -> Result<i64, ConfigError> {
    match cfg.get("version") {
        None => Ok(fallback),
        Some(v) => v.as_i64().ok_or(ConfigError::InvalidVersion),
    }
}

/// Port of `ensureSameVersion`.
fn ensure_same_version(
    base: &serde_json::Map<String, Value>,
    override_map: &serde_json::Map<String, Value>,
) -> Result<(), ConfigError> {
    let base_version = extract_version(base, 2)?;
    let override_version = extract_version(override_map, base_version)?;

    if base_version != override_version {
        return Err(ConfigError::OverrideVersionMismatch);
    }

    Ok(())
}

/// Port of `parseExtendsPaths`.
fn parse_extends_paths(val: &Value) -> Result<Vec<String>, ConfigError> {
    let items = val.as_array().ok_or(ConfigError::ExtendsNotList)?;

    items
        .iter()
        .map(|item| {
            item.as_str()
                .map(String::from)
                .ok_or(ConfigError::ExtendsItemNotString)
        })
        .collect()
}

/// Port of `loadFragment`/`parseFragment`.
fn load_fragment(abs_path: &std::path::Path) -> Result<Value, ConfigError> {
    let data = std::fs::read(abs_path)
        .map_err(|_| ConfigError::ConfigFileNotFound(abs_path.display().to_string()))?;

    serde_yaml::from_slice(&data).map_err(|err| ConfigError::InvalidYAML(err.to_string()))
}

/// Port of `resolveExtends`. `fetcher` resolves `https://` fragment
/// references (see this module's doc comment); `element_sources`, when
/// present, records which remote fragment each top-level deployer came
/// from, for `fetch_deployer_files` to later download referenced files
/// against.
#[allow(clippy::too_many_arguments)]
pub(super) fn resolve_extends(
    config_path: &std::path::Path,
    raw_config: Value,
    is_fragment: bool,
    visited: &mut std::collections::HashSet<std::path::PathBuf>,
    used_fragments: &mut std::collections::HashMap<String, String>,
    fetcher: &dyn RemoteFetcher,
    mut element_sources: Option<&mut std::collections::HashMap<String, RemoteElement>>,
) -> Result<Value, ConfigError> {
    let Value::Object(mut base_map) = raw_config else {
        return Ok(raw_config);
    };

    let Some(extends_val) = base_map.get("extends").cloned() else {
        return Ok(Value::Object(base_map));
    };

    if is_fragment {
        return Err(ConfigError::FragmentHasExtends);
    }

    let extends_paths = parse_extends_paths(&extends_val)?;

    let base_dir = config_path
        .parent()
        .unwrap_or_else(|| std::path::Path::new("."));

    let mut merged = Value::Object(serde_json::Map::new());

    for rel_path in &extends_paths {
        let fragment = if rel_path.starts_with(REMOTE_FRAGMENT_SCHEME) {
            let url = url_parse(rel_path).ok_or(ConfigError::InvalidFragmentName)?;
            // Port of `fragmentNamePattern.MatchString(path.Base(parsedURL.Path))`:
            // only the URL path's basename is checked, unlike a local
            // fragment reference's full relative path.
            let basename = url.path.rsplit('/').next().unwrap_or("");
            if !is_caproni_fragment_filename(basename, "xianyun")
                && !is_caproni_fragment_filename(basename, "caproni")
            {
                return Err(ConfigError::InvalidFragmentName);
            }

            resolve_remote_fragment(
                config_path,
                rel_path,
                visited,
                used_fragments,
                fetcher,
                element_sources.as_deref_mut(),
            )?
        } else if rel_path.contains("://") {
            return Err(ConfigError::RemoteFragmentFetch(format!(
                "{rel_path}: only https:// is supported"
            )));
        } else {
            resolve_local_fragment(
                config_path,
                base_dir,
                rel_path,
                visited,
                used_fragments,
                fetcher,
            )?
        };

        merged = deep_merge(&merged, &fragment);
    }

    base_map.remove("extends");

    Ok(deep_merge(&merged, &Value::Object(base_map)))
}

/// A minimal `scheme://host/path` split, enough to validate a remote
/// fragment reference's path component against the fragment-name
/// convention. No `url` crate dependency was added for this one call site
/// (see `predefined.rs`'s `host_port` precedent, noted in
/// `PORT_NOTES.md`).
struct ParsedUrl {
    path: String,
}

fn url_parse(url: &str) -> Option<ParsedUrl> {
    let rest = url.strip_prefix(REMOTE_FRAGMENT_SCHEME)?;
    let path_start = rest.find('/')?;
    let path_and_query = &rest[path_start..];
    let path = path_and_query.split(['?', '#']).next().unwrap_or("");
    Some(ParsedUrl {
        path: path.to_string(),
    })
}

/// Port of `resolveLocalFragment`.
fn resolve_local_fragment(
    config_path: &std::path::Path,
    base_dir: &std::path::Path,
    rel_path: &str,
    visited: &mut std::collections::HashSet<std::path::PathBuf>,
    used_fragments: &mut std::collections::HashMap<String, String>,
    fetcher: &dyn RemoteFetcher,
) -> Result<Value, ConfigError> {
    let abs_frag_path = base_dir.join(rel_path);

    let rel = pathdiff(&abs_frag_path, base_dir);
    if rel.starts_with("..") {
        return Err(ConfigError::FragmentOutsideDir);
    }

    if !is_valid_fragment_name(rel_path) {
        return Err(ConfigError::InvalidFragmentName);
    }

    let canonical = abs_frag_path
        .canonicalize()
        .unwrap_or_else(|_| abs_frag_path.clone());
    let canonical_key = canonical.display().to_string();

    if used_fragments.contains_key(&canonical_key) {
        return Err(ConfigError::DuplicateExtends(rel_path.to_string()));
    }

    used_fragments.insert(
        canonical_key,
        config_path
            .file_name()
            .map(|n| n.to_string_lossy().into_owned())
            .unwrap_or_default(),
    );

    if visited.contains(&canonical) {
        return Err(ConfigError::CircularExtends);
    }

    let frag_map = load_fragment(&abs_frag_path)?;

    // Fragments are not allowed to extend further (isFragment=true), so no
    // `element_sources` are recorded for a local fragment's own deployers
    // (matching the Go original's `resolveLocalFragment`, which never
    // threads `elementSources` at all — only a *remote* fragment's
    // deployers can later need a file downloaded from that fragment's URL).
    resolve_extends(
        &abs_frag_path,
        frag_map,
        true,
        visited,
        used_fragments,
        fetcher,
        None,
    )
}

/// Port of `resolveRemoteFragment`.
fn resolve_remote_fragment(
    config_path: &std::path::Path,
    url: &str,
    visited: &mut std::collections::HashSet<std::path::PathBuf>,
    used_fragments: &mut std::collections::HashMap<String, String>,
    fetcher: &dyn RemoteFetcher,
    element_sources: Option<&mut std::collections::HashMap<String, RemoteElement>>,
) -> Result<Value, ConfigError> {
    if used_fragments.contains_key(url) {
        return Err(ConfigError::DuplicateExtends(url.to_string()));
    }

    used_fragments.insert(
        url.to_string(),
        config_path
            .file_name()
            .map(|n| n.to_string_lossy().into_owned())
            .unwrap_or_default(),
    );

    let data = fetcher.fetch(url)?;

    let frag_map: Value =
        serde_yaml::from_slice(&data).map_err(|err| ConfigError::InvalidYAML(err.to_string()))?;

    // A remote fragment cannot itself carry `extends:` (isFragment=true, and
    // `element_sources=None` for the same reason as a local fragment's own
    // nested resolution — see `resolve_local_fragment`'s comment).
    let frag_map = resolve_extends(
        std::path::Path::new(url),
        frag_map,
        true,
        visited,
        used_fragments,
        fetcher,
        None,
    )?;

    if let Some(sources) = element_sources {
        record_element_sources(sources, &frag_map, url);
    }

    Ok(frag_map)
}

/// Port of `recordElementSources`.
fn record_element_sources(
    sources: &mut std::collections::HashMap<String, RemoteElement>,
    frag_map: &Value,
    url: &str,
) {
    let Some(deployers) = frag_map.get("deployers").and_then(Value::as_object) else {
        return;
    };

    for (name, deployer) in deployers {
        let Some(d) = deployer.as_object() else {
            continue;
        };

        let values_file = d
            .get("helm")
            .and_then(|h| h.get("values_file"))
            .and_then(Value::as_str)
            .unwrap_or_default()
            .to_string();
        let kustomize_path = d
            .get("kustomize")
            .and_then(|k| k.get("path"))
            .and_then(Value::as_str)
            .unwrap_or_default()
            .to_string();

        sources.insert(
            format!("deployers/{name}"),
            RemoteElement {
                url: url.to_string(),
                values_file,
                kustomize_path,
            },
        );
    }
}

/// A minimal relative-path computation (`filepath.Rel` equivalent), scoped to
/// what fragment-outside-directory detection needs: whether `path` (already
/// joined onto `base`) escapes `base` via `..` segments. No `pathdiff` crate
/// dependency was added for this single call site.
fn pathdiff(path: &std::path::Path, base: &std::path::Path) -> std::path::PathBuf {
    use std::path::Component;

    fn normalize(p: &std::path::Path) -> Vec<Component<'_>> {
        let mut out: Vec<Component<'_>> = Vec::new();
        for c in p.components() {
            match c {
                Component::CurDir => {}
                Component::ParentDir => {
                    if matches!(out.last(), Some(Component::Normal(_))) {
                        out.pop();
                    } else {
                        out.push(c);
                    }
                }
                other => out.push(other),
            }
        }
        out
    }

    let path_parts = normalize(path);
    let base_parts = normalize(base);

    let common = path_parts
        .iter()
        .zip(base_parts.iter())
        .take_while(|(a, b)| a == b)
        .count();

    let mut result = std::path::PathBuf::new();
    for _ in common..base_parts.len() {
        result.push("..");
    }
    for part in &path_parts[common..] {
        result.push(part.as_os_str());
    }

    if result.as_os_str().is_empty() {
        result.push(".");
    }

    result
}

/// Port of `loadLocalOverride`: reads and parses `xianyun.local.yaml`
/// (or, as a compatibility alias, `caproni.local.yaml`) from the same
/// directory as `config_path`. Returns `None` (no error) if neither file
/// exists.
pub(super) fn load_local_override(
    config_path: &std::path::Path,
) -> Result<Option<serde_json::Map<String, Value>>, ConfigError> {
    let local_path = resolve_local_override_path(config_path);

    let data = match std::fs::read(&local_path) {
        Ok(d) => d,
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(err) => {
            return Err(ConfigError::InvalidYAML(format!(
                "reading {}: {err}",
                local_path.display()
            )));
        }
    };

    let value: Value =
        serde_yaml::from_slice(&data).map_err(|err| ConfigError::InvalidYAML(err.to_string()))?;

    match value {
        Value::Object(map) => Ok(Some(map)),
        Value::Null => Ok(Some(serde_json::Map::new())),
        _ => Err(ConfigError::InvalidYAML(format!(
            "{} must be a YAML mapping",
            local_path.display()
        ))),
    }
}

/// Port of `resolveLocalOverride`: reads `caproni.local.yaml` and resolves
/// the `extends:` it may carry. `used_fragments` is shared with the base
/// config's extends resolution so that a fragment cannot be extended from
/// both `caproni.yaml` and `caproni.local.yaml`.
pub(super) fn resolve_local_override(
    abs_path: &std::path::Path,
    used_fragments: &mut std::collections::HashMap<String, String>,
    fetcher: &dyn RemoteFetcher,
    element_sources: Option<&mut std::collections::HashMap<String, RemoteElement>>,
) -> Result<Option<Value>, ConfigError> {
    let Some(local_override) = load_local_override(abs_path)? else {
        return Ok(None);
    };

    let local_abs_path = resolve_local_override_path(abs_path);

    let mut visited = std::collections::HashSet::new();
    visited.insert(
        abs_path
            .canonicalize()
            .unwrap_or_else(|_| abs_path.to_path_buf()),
    );
    visited.insert(
        local_abs_path
            .canonicalize()
            .unwrap_or_else(|_| local_abs_path.clone()),
    );

    let resolved = resolve_extends(
        &local_abs_path,
        Value::Object(local_override),
        false,
        &mut visited,
        used_fragments,
        fetcher,
        element_sources,
    )?;

    Ok(Some(resolved))
}

/// Port of `applyLocalOverride`: merges `override_val` onto `raw_config` and
/// returns the merged value. If `raw_config` is not a mapping, the override
/// is ignored and `raw_config` is returned unchanged (matching the Go
/// original's warn-and-ignore behavior, minus the log line).
pub(super) fn apply_local_override(
    raw_config: Value,
    override_val: Value,
) -> Result<Value, ConfigError> {
    let (Value::Object(base_map), Value::Object(override_map)) = (&raw_config, &override_val)
    else {
        return Ok(raw_config);
    };

    ensure_same_version(base_map, override_map)?;

    Ok(deep_merge(&raw_config, &override_val))
}

/// Primary filename read from each edit-mode repository directory. Port
/// of `caproniProjectFilename`. `caproni-project.yaml` is supported as a
/// compatibility alias when `xianyun-project.yaml` is absent.
const CAPRONI_PROJECT_FILENAME: &str = "xianyun-project.yaml";
const CAPRONI_PROJECT_FILENAME_ALIAS: &str = "caproni-project.yaml";
const RELOADERS_KEY: &str = "reloaders";

/// Compiles and validates `frag` against `schema/caproni-project.schema.json`.
/// That schema's `reloaders`/`lifecycle_hooks` properties `$ref` into
/// `schema/config.v2.schema.json`, so the v2 schema is registered as a
/// dependency resource under the URL the relative `$ref` resolves against
/// (`https://gitlab.com/schemas/config.v2.schema.json` — not the v2 schema's
/// own `$id`, matching the Go original's `compileProjectSchema`). No caching
/// across calls, for the same reason `validate_schema_v2` has none: see its
/// doc comment.
pub(super) fn validate_project_file_schema(frag: &Value) -> Result<(), ConfigError> {
    const V2_SCHEMA_JSON: &str = include_str!("../../../../schema/config.v2.schema.json");
    const PROJECT_SCHEMA_JSON: &str =
        include_str!("../../../../schema/caproni-project.schema.json");

    const V2_SCHEMA_URL: &str = "https://gitlab.com/schemas/config.v2.schema.json";

    let v2_doc: Value = serde_json::from_str(V2_SCHEMA_JSON)
        .map_err(|err| ConfigError::SchemaValidation(format!("parsing config schema v2: {err}")))?;
    let project_doc: Value = serde_json::from_str(PROJECT_SCHEMA_JSON).map_err(|err| {
        ConfigError::SchemaValidation(format!("parsing caproni-project schema: {err}"))
    })?;

    let v2_resource = jsonschema::Resource::from_contents(v2_doc).map_err(|err| {
        ConfigError::SchemaValidation(format!(
            "adding v2 schema resource for project schema: {err}"
        ))
    })?;

    let compiled = jsonschema::options()
        .with_resource(V2_SCHEMA_URL, v2_resource)
        .build(&project_doc)
        .map_err(|err| {
            ConfigError::SchemaValidation(format!("compiling caproni-project schema: {err}"))
        })?;

    let errors: Vec<String> = compiled
        .iter_errors(frag)
        .map(|e| {
            let path = e.instance_path.to_string();
            if path.is_empty() {
                e.to_string()
            } else {
                format!("{path}: {e}")
            }
        })
        .collect();

    if errors.is_empty() {
        Ok(())
    } else {
        Err(ConfigError::SchemaValidation(errors.join("; ")))
    }
}

/// Checks that every reloader in `frag` references `repo_name`. Structural
/// key validation is handled by the JSON schema
/// ([`validate_project_file_schema`]). Port of `validateRepoDeployersFragment`.
pub(super) fn validate_repo_deployers_fragment(
    frag: &Value,
    repo_name: &str,
) -> Result<(), ConfigError> {
    let Some(reloaders_val) = frag.get(RELOADERS_KEY) else {
        return Ok(());
    };

    let Some(reloaders) = reloaders_val.as_object() else {
        return Err(ConfigError::RepoFragmentOnlyReloaders);
    };

    for (name, val) in reloaders {
        let Some(entry) = val.as_object() else {
            continue;
        };

        let repo = entry
            .get("repository")
            .and_then(Value::as_str)
            .unwrap_or("");
        if repo != repo_name {
            return Err(ConfigError::RepoFragmentWrongRepository {
                name: name.clone(),
                repo: repo.to_string(),
                expected: repo_name.to_string(),
            });
        }
    }

    Ok(())
}

/// Reads and parses `xianyun-project.yaml` (or, as a compatibility
/// alias, `caproni-project.yaml`) from `dir`. Returns `Ok(None)` (no
/// error) if neither file exists. Port of `loadRepoDeployersFragment`.
fn load_repo_deployers_fragment(dir: &std::path::Path) -> Result<Option<Value>, ConfigError> {
    let primary_path = dir.join(CAPRONI_PROJECT_FILENAME);
    let frag_path = if primary_path.is_file() {
        primary_path
    } else {
        dir.join(CAPRONI_PROJECT_FILENAME_ALIAS)
    };

    let data = match std::fs::read(&frag_path) {
        Ok(d) => d,
        Err(err) if err.kind() == std::io::ErrorKind::NotFound => return Ok(None),
        Err(err) => {
            return Err(ConfigError::InvalidYAML(format!(
                "reading {}: {err}",
                frag_path.display()
            )));
        }
    };

    let mut frag: Value =
        serde_yaml::from_slice(&data).map_err(|err| ConfigError::InvalidYAML(err.to_string()))?;

    // Drop version so it cannot mask or conflict with the base config's version.
    if let Value::Object(map) = &mut frag {
        map.remove("version");
    }

    Ok(Some(frag))
}

/// Loads `caproni-project.yaml` from each repository directory that exists
/// on disk, and merges them as lower-precedence fragments beneath
/// `base_config` (`base_config` keys always win). Repositories are
/// processed in alphabetical order for determinism.
///
/// Each fragment may define `reloaders` (which must reference the owning
/// repository, and names must be unique across all repo fragments) and/or
/// `lifecycle_hooks` (which are appended to the owning repository's
/// `lifecycle_hooks` in `base_config`). Port of `applyCaproniProject`.
pub(super) fn apply_caproni_project(
    base_config: Value,
    config_dir: &std::path::Path,
) -> Result<Value, ConfigError> {
    let Some(repos) = base_config.get("repositories").and_then(Value::as_object) else {
        return Ok(base_config);
    };

    let mut repo_names: Vec<&String> = repos.keys().collect();
    repo_names.sort();

    let mut all_reloaders = serde_json::Map::new();
    let mut repo_hooks: Vec<(String, Vec<Value>)> = Vec::new();

    for repo_name in repo_names {
        let Some(repo) = repos.get(repo_name).and_then(Value::as_object) else {
            continue;
        };

        let edit_mode = repo
            .get("edit_mode")
            .and_then(Value::as_bool)
            .unwrap_or(false);
        if !edit_mode {
            continue;
        }

        let dir_str = repo.get("directory").and_then(Value::as_str).unwrap_or("");
        if dir_str.is_empty() {
            continue;
        }

        let dir_path = std::path::Path::new(dir_str);
        let dir = if dir_path.is_absolute() {
            dir_path.to_path_buf()
        } else {
            config_dir.join(dir_path)
        };

        let Some(frag) = load_repo_deployers_fragment(&dir)? else {
            continue;
        };

        let is_empty = frag.as_object().is_none_or(serde_json::Map::is_empty);
        if is_empty {
            continue;
        }

        validate_project_file_schema(&frag)?;
        validate_repo_deployers_fragment(&frag, repo_name)?;

        if let Some(reloaders) = frag.get(RELOADERS_KEY).and_then(Value::as_object) {
            for (name, val) in reloaders {
                if all_reloaders.contains_key(name) {
                    return Err(ConfigError::RepoFragmentDuplicateReloader(name.clone()));
                }

                all_reloaders.insert(name.clone(), val.clone());
            }
        }

        if let Some(hooks) = frag.get(LIFECYCLE_HOOKS_KEY).and_then(Value::as_array)
            && !hooks.is_empty()
        {
            repo_hooks.push((repo_name.clone(), hooks.clone()));
        }
    }

    if all_reloaders.is_empty() && repo_hooks.is_empty() {
        return Ok(base_config);
    }

    let mut merged = base_config;

    if !all_reloaders.is_empty() {
        let reloaders_overlay = Value::Object(serde_json::Map::from_iter([(
            RELOADERS_KEY.to_string(),
            Value::Object(all_reloaders),
        )]));
        merged = deep_merge(&reloaders_overlay, &merged);
    }

    // Append project-file lifecycle_hooks to each repo's existing hooks.
    // deep_merge(base, fragment) puts base hooks first, project hooks
    // second (via LIFECYCLE_HOOKS_KEY's append-list handling above).
    if !repo_hooks.is_empty() {
        let mut repo_fragment = serde_json::Map::new();
        for (repo_name, hooks) in repo_hooks {
            repo_fragment.insert(
                repo_name,
                Value::Object(serde_json::Map::from_iter([(
                    LIFECYCLE_HOOKS_KEY.to_string(),
                    Value::Array(hooks),
                )])),
            );
        }

        let hooks_overlay = Value::Object(serde_json::Map::from_iter([(
            "repositories".to_string(),
            Value::Object(repo_fragment),
        )]));
        merged = deep_merge(&merged, &hooks_overlay);
    }

    Ok(merged)
}

/// Names a kustomize path that references an overlay embedded in the
/// caproni binary, not a directory to fetch from a remote fragment's URL.
/// Port of `builtinKustomizeScheme`/`isBuiltinKustomizePath`.
const BUILTIN_KUSTOMIZE_SCHEME: &str = "builtin:";

fn is_builtin_kustomize_path(path: &str) -> bool {
    path.starts_with(BUILTIN_KUSTOMIZE_SCHEME)
}

/// Reports whether `path` is a kustomize remote target: a URL whose scheme
/// kustomize can resolve itself, so it is not fetched from the fragment's
/// URL either. Port of `kustomize.IsRemoteTarget`/`URLScheme`, duplicated
/// here for the same reason the Go original duplicates it in `caproni.go`
/// rather than importing the `kustomize` backend package: the config layer
/// must not depend on a deployer implementation.
fn is_kustomize_remote_target(path: &str) -> bool {
    let Some(scheme_end) = path.find("://") else {
        return false;
    };

    matches!(
        path[..scheme_end].to_ascii_lowercase().as_str(),
        "http" | "https" | "ssh" | "file"
    )
}

/// Port of `fetchDeployerFiles`: downloads the values file a remote
/// fragment's deployer references, unless a higher-precedence layer (the
/// base config, a local fragment, or `caproni.local.yaml`) already replaced
/// that reference — in which case it belongs to the user's own config and
/// resolves against the config directory like any local deployer.
pub(super) fn fetch_deployer_files(
    cfg: &mut super::latest::CaproniConfig,
    element_sources: &std::collections::HashMap<String, RemoteElement>,
    fetcher: &dyn RemoteFetcher,
) -> Result<(), ConfigError> {
    let Some(deployers) = cfg.deployers.as_mut() else {
        return Ok(());
    };

    let names: Vec<String> = deployers.iter().map(|(k, _)| k.clone()).collect();

    for name in names {
        let Some(src) = element_sources.get(&format!("deployers/{name}")) else {
            continue;
        };

        if !is_remote_source(&src.url) {
            continue;
        }

        {
            let dep = deployers.get(&name).expect("name came from this map");
            if let Some(helm) = &dep.helm
                && helm.values_file != src.values_file
            {
                continue;
            }
            if let Some(kustomize) = &dep.kustomize
                && kustomize.path != src.kustomize_path
            {
                continue;
            }
        }

        let dep = deployers.get_mut(&name).expect("name came from this map");
        fetch_deployer_files_from_remote(&name, dep, &src.url, fetcher)?;
    }

    Ok(())
}

/// Port of `fetchDeployerFilesFromRemote`. Receives the fragment's own file
/// references, so a kustomize path that is a local directory is rejected:
/// it lives on the fragment's host and cannot be downloaded.
fn fetch_deployer_files_from_remote(
    _name: &str,
    deployer: &mut super::latest::DeployerConfig,
    frag_url: &str,
    fetcher: &dyn RemoteFetcher,
) -> Result<(), ConfigError> {
    if let Some(kustomize) = &deployer.kustomize
        && !is_builtin_kustomize_path(&kustomize.path)
        && !is_kustomize_remote_target(&kustomize.path)
    {
        return Err(ConfigError::RemoteFragmentDirRef);
    }

    let Some(helm) = &mut deployer.helm else {
        return Ok(());
    };

    if helm.values_file.is_empty() || std::path::Path::new(&helm.values_file).is_absolute() {
        return Ok(());
    }

    helm.values_file = fetch_relative_file(fetcher, frag_url, &helm.values_file)?;

    Ok(())
}

/// A minimal `base.ResolveReference(ref)` equivalent, scoped to what
/// resolving a fragment-relative file reference needs: replace the base
/// URL's final path segment with `rel_path`. No `url` crate dependency was
/// added for this one call site.
fn resolve_relative_url(base: &str, rel_path: &str) -> Result<String, ConfigError> {
    if rel_path.contains("://") {
        return Ok(rel_path.to_string());
    }

    let last_slash = base
        .rfind('/')
        .ok_or_else(|| ConfigError::RemoteFragmentFetch(base.to_string()))?;

    Ok(format!(
        "{}/{}",
        &base[..last_slash],
        rel_path.trim_start_matches("./")
    ))
}

/// A deterministic on-disk path for a fetched remote file, keyed by its URL.
/// Stands in for the Go original's `filecache.Cache`-managed path (see this
/// module's doc comment on the caching scope reduction).
fn cache_file_path(url: &str) -> std::path::PathBuf {
    use sha2::{Digest, Sha256};

    let mut hasher = Sha256::new();
    hasher.update(url.as_bytes());
    let hash = hasher.finalize();
    let hex: String = hash.iter().map(|b| format!("{b:02x}")).collect();

    std::env::temp_dir()
        .join("xianyun-remote-fragments")
        .join(hex)
}

/// Port of `fetchRelativeFile`: fetches a file relative to a fragment URL
/// and persists it to a local path, returning that path.
///
/// **Divergence, reproducing Go's own observable quirk rather than fixing
/// it**: the Go original's `filecache.Cache.GetFile` cannot distinguish "no
/// file has ever been cached for this key" from "a stale file exists and
/// refreshing it failed" — both return the would-be cache path with no
/// error, on the theory that a stale-but-present file is still usable. On a
/// cold cache (the only case this crate's fetcher reproduces — see the
/// module doc comment), that means a *failed* fetch still returns a path,
/// just one nothing was ever written to. The caller (this port's
/// `fetch_deployer_files_from_remote`) has no way to tell the difference
/// either, exactly as in Go, so `deployer.Helm.ValuesFile` ends up pointing
/// at a nonexistent path — and this port's own `validate_semantics`
/// "values file not found" check is what actually surfaces the failure,
/// not this function. `TestLoadCaproniConfig_ExtendsRemoteFragmentMissingValuesFile_Fails`
/// pins exactly this externally-observable chain.
fn fetch_relative_file(
    fetcher: &dyn RemoteFetcher,
    frag_url: &str,
    rel_path: &str,
) -> Result<String, ConfigError> {
    let file_url = resolve_relative_url(frag_url, rel_path)?;
    let path = cache_file_path(&file_url);

    if let Ok(data) = fetcher.fetch(&file_url) {
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).map_err(|err| {
                ConfigError::RemoteFragmentFetch(format!("persisting cache entry: {err}"))
            })?;
        }
        std::fs::write(&path, &data).map_err(|err| {
            ConfigError::RemoteFragmentFetch(format!("persisting cache entry: {err}"))
        })?;
    }

    Ok(path.to_string_lossy().into_owned())
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::config::global::GlobalConfig;
    use serde_json::json;
    use std::fs;

    fn write_test_config(content: &str) -> (tempfile::TempDir, String) {
        let dir = tempfile::tempdir().unwrap();
        let path = dir.path().join("caproni.yaml");
        fs::write(&path, content).unwrap();
        (dir, path.to_string_lossy().into_owned())
    }

    /// Port of the Go `writeLocalOverride` helper.
    fn write_local_override(config_path: &str, content: &str) {
        let dir = std::path::Path::new(config_path).parent().unwrap();
        fs::write(dir.join("caproni.local.yaml"), content).unwrap();
    }

    /// Port of the Go `writeFragment` helper (used by extends: tests).
    fn write_fragment(dir: &std::path::Path, name: &str, content: &str) {
        fs::write(dir.join(name), content).unwrap();
    }

    fn load(path: String) -> Result<super::super::latest::CaproniConfig, ConfigError> {
        let gc = GlobalConfig {
            config_file: path,
            ..Default::default()
        };
        super::super::caproni::load_caproni_config(&gc)
    }

    // Port of TestDeepMerge (table-driven).
    #[test]
    fn deep_merge_cases() {
        struct Case {
            name: &'static str,
            dst: Value,
            src: Value,
            want: Value,
        }

        let cases = vec![
            Case {
                name: "scalar override",
                dst: json!({"a": "original", "b": "keep"}),
                src: json!({"a": "override"}),
                want: json!({"a": "override", "b": "keep"}),
            },
            Case {
                name: "new key added",
                dst: json!({"a": "original"}),
                src: json!({"b": "new"}),
                want: json!({"a": "original", "b": "new"}),
            },
            Case {
                name: "nested map merge",
                dst: json!({"outer": {"keep": "kept", "override": "original"}}),
                src: json!({"outer": {"override": "new", "added": "yes"}}),
                want: json!({"outer": {"keep": "kept", "override": "new", "added": "yes"}}),
            },
            Case {
                name: "slice replaces",
                dst: json!({"items": ["a", "b"]}),
                src: json!({"items": ["c"]}),
                want: json!({"items": ["c"]}),
            },
            Case {
                name: "additional_hostnames appended",
                dst: json!({"additional_hostnames": ["base.local"]}),
                src: json!({"additional_hostnames": ["fragment.local"]}),
                want: json!({"additional_hostnames": ["base.local", "fragment.local"]}),
            },
            Case {
                name: "lifecycle_hooks appended",
                dst: json!({"lifecycle_hooks": [{"type": "edit_mode_start", "script": "base.sh"}]}),
                src: json!({"lifecycle_hooks": [{"type": "edit_mode_start", "script": "override.sh"}]}),
                want: json!({"lifecycle_hooks": [
                    {"type": "edit_mode_start", "script": "base.sh"},
                    {"type": "edit_mode_start", "script": "override.sh"},
                ]}),
            },
            Case {
                name: "dynamic_overrides appended",
                dst: json!({"dynamic_overrides": [{"type": "inline", "value_map": {"crds.enabled": true}}]}),
                src: json!({"dynamic_overrides": [{"type": "inline", "value_map": {"prometheus.enabled": true}}]}),
                want: json!({"dynamic_overrides": [
                    {"type": "inline", "value_map": {"crds.enabled": true}},
                    {"type": "inline", "value_map": {"prometheus.enabled": true}},
                ]}),
            },
        ];

        for case in cases {
            let result = deep_merge(&case.dst, &case.src);
            assert_eq!(result, case.want, "{}", case.name);
        }
    }

    // Port of TestDeepMerge_NullDeletes.
    #[test]
    fn deep_merge_null_deletes_cases() {
        struct Case {
            name: &'static str,
            dst: Value,
            src: Value,
            want: Value,
        }

        let cases = vec![
            Case {
                name: "null overlay deletes existing scalar key",
                dst: json!({"a": "original", "b": "keep"}),
                src: json!({"a": null}),
                want: json!({"b": "keep"}),
            },
            Case {
                name: "null overlay deletes existing map key",
                dst: json!({"traefik": {"type": "helm"}, "keep": "kept"}),
                src: json!({"traefik": null}),
                want: json!({"keep": "kept"}),
            },
            Case {
                name: "null overlay on absent key is a harmless no-op",
                dst: json!({"a": "original"}),
                src: json!({"b": null}),
                want: json!({"a": "original"}),
            },
            Case {
                name: "nested null deletes only the inner key",
                dst: json!({"deployers": {"traefik": {"type": "helm"}, "gitlab": {"type": "helm"}}}),
                src: json!({"deployers": {"traefik": null}}),
                want: json!({"deployers": {"gitlab": {"type": "helm"}}}),
            },
            Case {
                name: "null deletes an append-slice key (lifecycle_hooks)",
                dst: json!({"lifecycle_hooks": [{"type": "edit_mode_start"}]}),
                src: json!({"lifecycle_hooks": null}),
                want: json!({}),
            },
            Case {
                name: "null drops every inherited dynamic_overrides entry",
                dst: json!({"dynamic_overrides": [{"type": "inline"}]}),
                src: json!({"dynamic_overrides": null}),
                want: json!({}),
            },
            Case {
                name: "empty-map overlay on existing map is a no-op",
                dst: json!({"traefik": {"type": "helm"}}),
                src: json!({"traefik": {}}),
                want: json!({"traefik": {"type": "helm"}}),
            },
        ];

        for case in cases {
            let result = deep_merge(&case.dst, &case.src);
            assert_eq!(result, case.want, "{}", case.name);
        }
    }

    // Port of TestDeepMerge_DstNotModified.
    #[test]
    fn deep_merge_dst_not_modified() {
        let dst = json!({"a": "original"});
        let src = json!({"a": "override", "b": "new"});

        let _ = deep_merge(&dst, &src);

        assert_eq!(dst["a"], json!("original"));
        assert!(dst.get("b").is_none());
    }

    // Port of TestLoadCaproniConfig_LocalOverrideNullDeployerRemoves.
    #[test]
    fn local_override_null_deployer_removes() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
deployers:
  extra-ns:
    type: namespace
    namespace:
      namespaces:
        - extra
  keep-ns:
    type: namespace
    namespace:
      namespaces:
        - keep
";
        let (_dir, config_path) = write_test_config(base);
        write_local_override(&config_path, "deployers:\n  extra-ns: null\n");

        let cfg = load(config_path).expect("load should succeed");
        let deployers = cfg.deployers.unwrap();
        assert!(
            !deployers.has(&"extra-ns".to_string()),
            "null override removes the deployer"
        );
        assert!(
            deployers.has(&"keep-ns".to_string()),
            "sibling deployer survives"
        );
    }

    // Port of TestLoadCaproniConfig_LocalOverrideDeletesExtendedDeployer.
    #[test]
    fn local_override_deletes_extended_deployer() {
        let tmp_dir = tempfile::tempdir().unwrap();

        write_fragment(
            tmp_dir.path(),
            "caproni.infra.yaml",
            "
deployers:
  shared-ns:
    type: namespace
    namespace:
      namespaces:
        - shared
  other-ns:
    type: namespace
    namespace:
      namespaces:
        - other
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.infra.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
deployers:
  my-app:
    type: namespace
    namespace:
      namespaces:
        - my-app
",
        )
        .unwrap();

        let config_path = config_path.to_string_lossy().into_owned();
        write_local_override(&config_path, "deployers:\n  shared-ns: null\n");

        let cfg = load(config_path).expect("load should succeed");
        let deployers = cfg.deployers.unwrap();
        assert!(
            !deployers.has(&"shared-ns".to_string()),
            "a null in caproni.local.yaml must delete a deployer the extended fragment supplies"
        );
        assert!(
            deployers.has(&"other-ns".to_string()),
            "deleting one extended deployer must not affect its siblings"
        );
        assert!(
            deployers.has(&"my-app".to_string()),
            "the deployer caproni.yaml declares itself survives the override merge"
        );
    }

    // Port of TestLoadCaproniConfig_LocalOverrideEmptyMapDeployerIsNoOp.
    #[test]
    fn local_override_empty_map_deployer_is_noop() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
deployers:
  extra-ns:
    type: namespace
    namespace:
      namespaces:
        - extra
";
        let (_dir, config_path) = write_test_config(base);
        write_local_override(&config_path, "deployers:\n  extra-ns: {}\n");

        let cfg = load(config_path).expect("load should succeed");
        let deployers = cfg.deployers.unwrap();
        assert!(deployers.has(&"extra-ns".to_string()));

        let dep = deployers.get(&"extra-ns".to_string()).unwrap();
        let ns = dep
            .namespace
            .as_ref()
            .expect("empty-map override left the namespace config intact");
        assert_eq!(ns.namespaces, vec!["extra".to_string()]);
    }

    // The remote-fragment tests below (`TestLoadCaproniConfig_ExtendsRemote*`)
    // are all ported with real bodies using `FakeFetcher`; see this module's
    // doc comment.

    // Port of TestLoadCaproniConfig_LocalOverrideAbsent.
    #[test]
    fn local_override_absent() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
";
        let (_dir, config_path) = write_test_config(base);
        let cfg = load(config_path).expect("load should succeed");
        assert_eq!(cfg.cluster.driver, "colima");
    }

    // Port of TestLoadCaproniConfig_LocalOverrideScalar.
    #[test]
    fn local_override_scalar() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
";
        let (_dir, config_path) = write_test_config(base);
        write_local_override(&config_path, "cluster:\n  colima:\n    memory: 16GiB\n");

        let cfg = load(config_path).expect("load should succeed");
        assert_eq!(cfg.cluster.colima.as_ref().unwrap().memory, "16GiB");
        assert_eq!(
            cfg.cluster.colima.as_ref().unwrap().cores,
            2,
            "cores unchanged by override"
        );
    }

    // Port of TestLoadCaproniConfig_LocalOverrideAddsReloader.
    #[test]
    fn local_override_adds_reloader() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories:
  app:
    repository: https://example.com/app.git
    directory: ./app/
";
        let (_dir, config_path) = write_test_config(base);
        write_local_override(
            &config_path,
            "
reloaders:
  app:
    type: mirror
    repository: app
    edit_mode: true
    mirror:
      target:
        namespace: default
        kubernetes_type: deployment
        name: app-deployment
      edit_mode_processes:
        server:
          command: bin/server
",
        );

        let cfg = load(config_path).expect("load should succeed");
        let reloaders = cfg.reloaders.unwrap();
        assert_eq!(reloaders.len(), 1);
        let reloader = reloaders.get(&"app".to_string()).unwrap();
        assert!(reloader.edit_mode);
    }

    // Port of TestLoadCaproniConfig_VersionMismatch.
    #[test]
    fn version_mismatch() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories:
  app:
    repository: https://example.com/app.git
    directory: ./app/
";
        let (_dir, config_path) = write_test_config(base);
        write_local_override(&config_path, "version: 1\n");

        let err = load(config_path).expect_err("version mismatch should fail");
        assert!(matches!(err, ConfigError::OverrideVersionMismatch));
        assert_eq!(
            err.to_string(),
            "tried merging configs with different versions"
        );
    }

    // Port of TestLoadCaproniConfig_LocalOverrideLifecycleHooksAppend.
    #[test]
    fn local_override_lifecycle_hooks_append() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories:
  app:
    repository: https://example.com/app.git
    directory: ./app/
    lifecycle_hooks:
      - type: edit_mode_start
        script: ./base-hook.sh
";
        let (_dir, config_path) = write_test_config(base);
        write_local_override(
            &config_path,
            "
repositories:
  app:
    lifecycle_hooks:
      - type: edit_mode_start
        script: ./local-hook.sh
",
        );

        let cfg = load(config_path).expect("load should succeed");
        let repos = cfg.repositories.unwrap();
        let repo = repos.get(&"app".to_string()).unwrap();
        assert_eq!(repo.lifecycle_hooks.len(), 2);
        assert_eq!(repo.lifecycle_hooks[0].script, "./base-hook.sh");
        assert_eq!(repo.lifecycle_hooks[1].script, "./local-hook.sh");
    }

    // Port of TestLoadCaproniConfig_LocalOverrideInvalidYAML.
    #[test]
    fn local_override_invalid_yaml() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
";
        let (_dir, config_path) = write_test_config(base);
        write_local_override(&config_path, "invalid: [yaml");

        let err = load(config_path).expect_err("invalid yaml should fail");
        assert!(matches!(err, ConfigError::InvalidYAML(_)));
    }

    // Port of TestLoadCaproniConfig_LocalOverrideNonMapping.
    #[test]
    fn local_override_non_mapping() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
";
        let (_dir, config_path) = write_test_config(base);
        write_local_override(&config_path, "- item1\n- item2\n");

        let err = load(config_path).expect_err("non-mapping override should fail");
        assert!(matches!(err, ConfigError::InvalidYAML(_)));
    }

    // Port of TestLoadCaproniConfig_ExtendsAddsRepository.
    #[test]
    fn extends_adds_repository() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(
            tmp_dir.path(),
            "caproni.extra.yaml",
            "
repositories:
  extra:
    repository: https://example.com/extra.git
    directory: ./extra/
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.extra.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories:
  main:
    repository: https://example.com/main.git
    directory: ./main/
",
        )
        .unwrap();

        let cfg = load(config_path.to_string_lossy().into_owned()).expect("load should succeed");
        let repos = cfg.repositories.unwrap();
        assert_eq!(repos.len(), 2);
        assert!(repos.has(&"main".to_string()));
        assert!(repos.has(&"extra".to_string()));
    }

    // Port of TestLoadCaproniConfig_ExtendsBaseWinsOnConflict.
    #[test]
    fn extends_base_wins_on_conflict() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(
            tmp_dir.path(),
            "caproni.frag.yaml",
            "
cluster:
  colima:
    memory: 32GiB
    cores: 8
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.frag.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let cfg = load(config_path.to_string_lossy().into_owned()).expect("load should succeed");
        assert_eq!(cfg.cluster.colima.as_ref().unwrap().memory, "4GiB");
        assert_eq!(cfg.cluster.colima.as_ref().unwrap().cores, 2);
    }

    // Port of TestLoadCaproniConfig_ExtendsMultipleFragmentsLeftToRight.
    #[test]
    fn extends_multiple_fragments_left_to_right() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(
            tmp_dir.path(),
            "caproni.a.yaml",
            "
repositories:
  a:
    repository: https://example.com/a.git
    directory: ./a/
  shared:
    repository: https://example.com/shared-from-a.git
    directory: ./shared/
",
        );
        write_fragment(
            tmp_dir.path(),
            "caproni.b.yaml",
            "
repositories:
  b:
    repository: https://example.com/b.git
    directory: ./b/
  shared:
    repository: https://example.com/shared-from-b.git
    directory: ./shared/
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.a.yaml
  - ./caproni.b.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let cfg = load(config_path.to_string_lossy().into_owned()).expect("load should succeed");
        let repos = cfg.repositories.unwrap();
        assert!(repos.has(&"a".to_string()));
        assert!(repos.has(&"b".to_string()));
        let shared = repos.get(&"shared".to_string()).unwrap();
        assert_eq!(shared.repository, "https://example.com/shared-from-b.git");
    }

    // Port of TestLoadCaproniConfig_ExtendsFragmentHasExtends_Fails.
    #[test]
    fn extends_fragment_has_extends_fails() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(
            tmp_dir.path(),
            "caproni.frag.yaml",
            "
extends:
  - ./caproni.other.yaml
repositories:
  frag:
    repository: https://example.com/frag.git
    directory: ./frag/
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.frag.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let err = load(config_path.to_string_lossy().into_owned())
            .expect_err("fragment with extends should fail");
        assert!(matches!(err, ConfigError::FragmentHasExtends));
    }

    // Port of TestLoadCaproniConfig_ExtendsMainConfig_Fails.
    #[test]
    fn extends_main_config_fails() {
        let tmp_dir = tempfile::tempdir().unwrap();
        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let err =
            load(config_path.to_string_lossy().into_owned()).expect_err("self-extends should fail");
        assert!(matches!(err, ConfigError::CircularExtends));
    }

    // Port of TestLoadCaproniConfig_ExtendsLocalOverride_Fails.
    #[test]
    fn extends_local_override_fails() {
        let tmp_dir = tempfile::tempdir().unwrap();
        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        write_local_override(
            &config_path.to_string_lossy(),
            "
extends:
  - ./caproni.local.yaml
",
        );

        let err = load(config_path.to_string_lossy().into_owned())
            .expect_err("local override extending itself should fail");
        assert!(matches!(err, ConfigError::CircularExtends));
    }

    // Port of TestLoadCaproniConfig_ExtendsMissingFragment_Fails.
    #[test]
    fn extends_missing_fragment_fails() {
        let tmp_dir = tempfile::tempdir().unwrap();
        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.nonexistent.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let err = load(config_path.to_string_lossy().into_owned())
            .expect_err("missing fragment should fail");
        assert!(matches!(err, ConfigError::ConfigFileNotFound(_)));
    }

    // Port of TestLoadCaproniConfig_ExtendsFragmentInvalidYAML_Fails.
    #[test]
    fn extends_fragment_invalid_yaml_fails() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(tmp_dir.path(), "caproni.bad.yaml", "invalid: [yaml");

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.bad.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let err = load(config_path.to_string_lossy().into_owned())
            .expect_err("invalid fragment yaml should fail");
        assert!(matches!(err, ConfigError::InvalidYAML(_)));
    }

    // Port of TestLoadCaproniConfig_ExtendsWithLocalOverride.
    #[test]
    fn extends_with_local_override() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(
            tmp_dir.path(),
            "caproni.frag.yaml",
            "
reloaders:
  app:
    type: mirror
    repository: app
    mirror:
      target:
        namespace: default
        kubernetes_type: deployment
        name: app
      edit_mode_processes:
        server:
          command: bin/server
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.frag.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories:
  app:
    repository: https://example.com/app.git
    directory: ./app/
",
        )
        .unwrap();

        write_local_override(
            &config_path.to_string_lossy(),
            "
reloaders:
  app:
    edit_mode: true
",
        );

        let cfg = load(config_path.to_string_lossy().into_owned()).expect("load should succeed");
        let reloaders = cfg.reloaders.unwrap();
        let reloader = reloaders.get(&"app".to_string()).unwrap();
        assert!(
            reloader.edit_mode,
            "local override should set edit_mode=true"
        );
    }

    // Port of TestLoadCaproniConfig_LocalOverrideExtendsFragment.
    #[test]
    fn local_override_extends_fragment() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(
            tmp_dir.path(),
            "caproni.local-extra.yaml",
            "
reloaders:
  app:
    type: mirror
    repository: app
    edit_mode: true
    mirror:
      target:
        namespace: default
        kubernetes_type: deployment
        name: app
      edit_mode_processes:
        server:
          command: bin/server
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories:
  app:
    repository: https://example.com/app.git
    directory: ./app/
",
        )
        .unwrap();

        write_local_override(
            &config_path.to_string_lossy(),
            "
extends:
  - ./caproni.local-extra.yaml
",
        );

        let cfg = load(config_path.to_string_lossy().into_owned()).expect("load should succeed");
        let reloaders = cfg.reloaders.unwrap();
        let reloader = reloaders.get(&"app".to_string()).unwrap();
        assert!(reloader.edit_mode);
    }

    // Port of TestLoadCaproniConfig_SameFragmentInBaseAndLocal_Fails.
    #[test]
    fn same_fragment_in_base_and_local_fails() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(
            tmp_dir.path(),
            "caproni.frag.yaml",
            "
repositories:
  extra:
    repository: https://example.com/extra.git
    directory: ./extra/
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.frag.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        write_local_override(
            &config_path.to_string_lossy(),
            "
extends:
  - ./caproni.frag.yaml
",
        );

        let err = load(config_path.to_string_lossy().into_owned())
            .expect_err("using the same fragment twice should fail");
        assert!(matches!(err, ConfigError::DuplicateExtends(_)));
    }

    // Port of TestLoadCaproniConfig_LocalOverrideEmpty.
    #[test]
    fn local_override_empty() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
";
        let (_dir, config_path) = write_test_config(base);
        write_local_override(&config_path, "");

        let cfg = load(config_path).expect("load should succeed");
        assert_eq!(cfg.cluster.driver, "colima");
    }

    // Port of TestLoadCaproniConfig_ExtendsLifecycleHooksAppend.
    #[test]
    fn extends_lifecycle_hooks_append() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(
            tmp_dir.path(),
            "caproni.hooks.yaml",
            "
repositories:
  app:
    repository: https://example.com/app.git
    directory: ./app/
    lifecycle_hooks:
      - type: edit_mode_start
        script: ./fragment-hook.sh
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.hooks.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories:
  app:
    repository: https://example.com/app.git
    directory: ./app/
    lifecycle_hooks:
      - type: edit_mode_start
        script: ./base-hook.sh
",
        )
        .unwrap();

        let cfg = load(config_path.to_string_lossy().into_owned()).expect("load should succeed");
        let repos = cfg.repositories.unwrap();
        let repo = repos.get(&"app".to_string()).unwrap();
        assert_eq!(repo.lifecycle_hooks.len(), 2);
        assert_eq!(repo.lifecycle_hooks[0].script, "./fragment-hook.sh");
        assert_eq!(repo.lifecycle_hooks[1].script, "./base-hook.sh");
    }

    // Port of TestLoadCaproniConfig_LocalOverrideAdditionalHostnamesAppend.
    #[test]
    fn local_override_additional_hostnames_append() {
        let base = "
version: 2
cluster:
  driver: colima
  network:
    hostname: test.local
    additional_hostnames:
      - base.local
  colima:
    memory: 4GiB
    cores: 2
repositories:
  app:
    repository: https://example.com/app.git
    directory: ./app/
";
        let (_dir, config_path) = write_test_config(base);
        write_local_override(
            &config_path,
            "
cluster:
  network:
    additional_hostnames:
      - local-override.local
",
        );

        let cfg = load(config_path).expect("load should succeed");
        let network = cfg.cluster.network.as_ref().unwrap();
        assert_eq!(
            network.additional_hostnames,
            vec!["base.local".to_string(), "local-override.local".to_string()]
        );
    }

    // Port of TestLoadCaproniConfig_ExtendsAdditionalHostnamesAppend.
    #[test]
    fn extends_additional_hostnames_append() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(
            tmp_dir.path(),
            "caproni.hostnames.yaml",
            "
cluster:
  network:
    additional_hostnames:
      - fragment.local
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.hostnames.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
    additional_hostnames:
      - base.local
  colima:
    memory: 4GiB
    cores: 2
repositories:
  app:
    repository: https://example.com/app.git
    directory: ./app/
",
        )
        .unwrap();

        let cfg = load(config_path.to_string_lossy().into_owned()).expect("load should succeed");
        let network = cfg.cluster.network.as_ref().unwrap();
        assert_eq!(
            network.additional_hostnames,
            vec!["fragment.local".to_string(), "base.local".to_string()]
        );
    }

    // Port of TestLoadCaproniConfig_ExtendsPathTraversal_Fails.
    #[test]
    fn extends_path_traversal_fails() {
        let tmp_dir = tempfile::tempdir().unwrap();
        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ../caproni.evil.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let err = load(config_path.to_string_lossy().into_owned())
            .expect_err("path traversal should fail");
        assert!(matches!(err, ConfigError::FragmentOutsideDir));
    }

    // Port of TestLoadCaproniConfig_ExtendsInvalidFragmentName_Fails.
    #[test]
    fn extends_invalid_fragment_name_fails() {
        let tmp_dir = tempfile::tempdir().unwrap();
        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./my-arbitrary-config.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let err = load(config_path.to_string_lossy().into_owned())
            .expect_err("invalid fragment name should fail");
        assert!(matches!(err, ConfigError::InvalidFragmentName));
    }

    // xianyun.<name>.yaml is a valid fragment name too, not just the
    // pre-rename caproni.<name>.yaml convention.
    #[test]
    fn extends_xianyun_prefixed_fragment_name_is_valid() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(tmp_dir.path(), "xianyun.infra.yaml", "\ndeployers: {}\n");

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./xianyun.infra.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        load(config_path.to_string_lossy().into_owned())
            .expect("xianyun.<name>.yaml fragment name must be accepted");
    }

    // Port of TestLoadCaproniConfig_ExtendsDuplicateFragment_Fails.
    #[test]
    fn extends_duplicate_fragment_fails() {
        let tmp_dir = tempfile::tempdir().unwrap();
        write_fragment(
            tmp_dir.path(),
            "caproni.frag.yaml",
            "
repositories:
  extra:
    repository: https://example.com/extra.git
    directory: ./extra/
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./caproni.frag.yaml
  - ./caproni.frag.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let err = load(config_path.to_string_lossy().into_owned())
            .expect_err("duplicate fragment should fail");
        assert!(matches!(err, ConfigError::DuplicateExtends(_)));
    }

    // Port of TestLoadCaproniConfig_ExtendsLocalPlainCaproniYAMLInSubdir.
    #[test]
    fn extends_local_plain_caproni_yaml_in_subdir() {
        let tmp_dir = tempfile::tempdir().unwrap();
        let sub_dir = tmp_dir.path().join("sub");
        fs::create_dir(&sub_dir).unwrap();
        write_fragment(
            &sub_dir,
            "caproni.yaml",
            "
repositories:
  local:
    repository: https://example.com/local.git
    directory: ./local/
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./sub/caproni.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let cfg = load(config_path.to_string_lossy().into_owned()).expect("load should succeed");
        assert!(cfg.repositories.unwrap().has(&"local".to_string()));
    }

    // Port of TestLoadCaproniConfig_ExtendsLocalFragmentRelativePaths: a local
    // fragment's relative paths are left untouched, resolved at load time
    // against the *main* config directory, not the fragment's own subdirectory.
    #[test]
    fn extends_local_fragment_relative_paths_helm_values_file() {
        let tmp_dir = tempfile::tempdir().unwrap();
        fs::write(tmp_dir.path().join("values.yaml"), "replicaCount: 3\n").unwrap();

        let sub_dir = tmp_dir.path().join("sub");
        fs::create_dir(&sub_dir).unwrap();
        write_fragment(
            &sub_dir,
            "caproni.gitlab.yaml",
            "
deployers:
  gitlab:
    type: helm
    helm:
      namespace: gitlab
      values_file: values.yaml
      release:
        name: gitlab
        chart: gitlab/gitlab
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./sub/caproni.gitlab.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let cfg = load(config_path.to_string_lossy().into_owned()).expect("load should succeed");
        let deployers = cfg.deployers.unwrap();
        let dep = deployers.get(&"gitlab".to_string()).unwrap();
        let got = &dep.helm.as_ref().unwrap().values_file;
        assert_eq!(got, "values.yaml");
        assert!(!std::path::Path::new(got).is_absolute());
    }

    // Companion sub-case of the same Go table test (kustomize path).
    #[test]
    fn extends_local_fragment_relative_paths_kustomize_path() {
        let tmp_dir = tempfile::tempdir().unwrap();
        fs::create_dir(tmp_dir.path().join("manifests")).unwrap();

        let sub_dir = tmp_dir.path().join("sub");
        fs::create_dir(&sub_dir).unwrap();
        write_fragment(
            &sub_dir,
            "caproni.gitlab.yaml",
            "
deployers:
  gitlab:
    type: kustomize
    kustomize:
      path: manifests
",
        );

        let config_path = tmp_dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            "
version: 2
extends:
  - ./sub/caproni.gitlab.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
",
        )
        .unwrap();

        let cfg = load(config_path.to_string_lossy().into_owned()).expect("load should succeed");
        let deployers = cfg.deployers.unwrap();
        let dep = deployers.get(&"gitlab".to_string()).unwrap();
        let got = &dep.kustomize.as_ref().unwrap().path;
        assert_eq!(got, "manifests");
        assert!(!std::path::Path::new(got).is_absolute());
    }

    /// A test double for [`RemoteFetcher`] that serves fixed responses from
    /// an in-memory map keyed by full URL, standing in for the Go original's
    /// `httptest.Server`-backed `serveFragments` helper. Unlike an actual
    /// mock HTTP server, this needs no TLS story for the `https://`-only
    /// scheme check (`is_remote_source`) to exercise: the URLs handed to
    /// `FakeFetcher::new` and embedded in a test's `caproni.yaml` fixture
    /// are already `https://fake-remote.test/...`, and `fetch` just looks
    /// them up rather than dispatching a real request. This is the same
    /// seam `UreqFetcher` is injected through in production, so the
    /// `resolve_extends`/`fetch_deployer_files` logic under test never
    /// knows the difference. (This session used this simpler in-process
    /// double instead of the `wiremock`+`tokio` approach this module's doc
    /// comment previously sketched — no real network call is exercised by
    /// any of these tests either way, since `RemoteFetcher` is exactly the
    /// injection seam `UreqFetcher`'s own logic sits behind, and a fake
    /// implementation of that trait needs no async runtime or TLS.)
    #[derive(Default)]
    struct FakeFetcher {
        responses: std::collections::HashMap<String, Vec<u8>>,
        // Mirrors `UreqFetcher`'s own "fetched at most once per instance"
        // cache, so `extends_remote_fragment`'s caching assertion (a repeat
        // `load_caproni_config_with_fetcher` call sharing one fetcher issues
        // no second request) exercises real caching behavior rather than a
        // fake that always re-serves the same canned response.
        cache: Mutex<std::collections::HashMap<String, Vec<u8>>>,
        hits: std::sync::atomic::AtomicU32,
    }

    impl FakeFetcher {
        fn new(pairs: &[(&str, &str)]) -> Self {
            Self {
                responses: pairs
                    .iter()
                    .map(|(k, v)| ((*k).to_string(), v.as_bytes().to_vec()))
                    .collect(),
                cache: Mutex::new(std::collections::HashMap::new()),
                hits: std::sync::atomic::AtomicU32::new(0),
            }
        }

        fn hit_count(&self) -> u32 {
            self.hits.load(std::sync::atomic::Ordering::SeqCst)
        }
    }

    impl RemoteFetcher for FakeFetcher {
        fn fetch(&self, url: &str) -> Result<Vec<u8>, ConfigError> {
            if let Some(cached) = self.cache.lock().unwrap().get(url) {
                return Ok(cached.clone());
            }

            self.hits.fetch_add(1, std::sync::atomic::Ordering::SeqCst);

            let body = self
                .responses
                .get(url)
                .ok_or_else(|| ConfigError::RemoteFragmentFetch(format!("{url}: not found")))?;

            if body.len() as u64 > MAX_FRAGMENT_BYTES {
                return Err(ConfigError::RemoteFragmentFetch(format!(
                    "{url}: response exceeds {MAX_FRAGMENT_BYTES} bytes"
                )));
            }

            self.cache
                .lock()
                .unwrap()
                .insert(url.to_string(), body.clone());

            Ok(body.clone())
        }
    }

    /// Base URL fixtures embed for a fake remote fragment host. Port of the
    /// Go `httptest.Server`'s `server.URL`.
    const FAKE_SERVER: &str = "https://fake-remote.test";

    fn load_with_fetcher(
        path: String,
        fetcher: &dyn RemoteFetcher,
    ) -> Result<super::super::latest::CaproniConfig, ConfigError> {
        let gc = GlobalConfig {
            config_file: path,
            ..Default::default()
        };
        super::super::caproni::load_caproni_config_with_fetcher(&gc, fetcher)
    }

    /// Port of the Go `baseConfigWithExtends` helper.
    fn base_config_with_extends(extends_url: &str) -> String {
        format!(
            "\nversion: 2\nextends:\n  - {extends_url}\ncluster:\n  driver: colima\n  network:\n    hostname: test.local\n  colima:\n    memory: 4GiB\n    cores: 2\nrepositories: {{}}\n"
        )
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteFragment (including its
    // "caching" subtest, folded into the same test body since Rust has no
    // subtest equivalent worth introducing for one assertion).
    #[test]
    fn extends_remote_fragment() {
        let frag_url = format!("{FAKE_SERVER}/caproni.extended.yaml");
        let fetcher = FakeFetcher::new(&[(
            frag_url.as_str(),
            "\nrepositories:\n  extended:\n    repository: https://example.com/extended.git\n    directory: ./extended/\n",
        )]);

        let base = format!(
            "\nversion: 2\nextends:\n  - {frag_url}\ncluster:\n  driver: colima\n  network:\n    hostname: test.local\n  colima:\n    memory: 4GiB\n    cores: 2\nrepositories:\n  base:\n    repository: https://example.com/base.git\n    directory: ./base/\n"
        );
        let (_dir, config_path) = write_test_config(&base);

        let cfg = load_with_fetcher(config_path.clone(), &fetcher).expect("load should succeed");
        let repos = cfg.repositories.as_ref().unwrap();
        assert_eq!(repos.len(), 2);

        let base_repo = repos.get(&"base".to_string()).unwrap();
        assert_eq!(base_repo.repository, "https://example.com/base.git");
        assert_eq!(base_repo.directory, "./base/");

        let extended_repo = repos.get(&"extended".to_string()).unwrap();
        assert_eq!(extended_repo.repository, "https://example.com/extended.git");
        assert_eq!(extended_repo.directory, "./extended/");

        assert_eq!(fetcher.hit_count(), 1);
        let cfg2 = load_with_fetcher(config_path, &fetcher).expect("load should succeed");
        assert_eq!(
            fetcher.hit_count(),
            1,
            "expected request count to stay at 1"
        );
        assert_eq!(
            serde_json::to_value(&cfg).unwrap(),
            serde_json::to_value(&cfg2).unwrap(),
            "second loaded config should be identical"
        );
    }

    // Port of TestLoadCaproniConfig_ExtendsRemotePlainCaproniYAML.
    #[test]
    fn extends_remote_plain_caproni_yaml() {
        let frag_url = format!("{FAKE_SERVER}/caproni.yaml");
        let fetcher = FakeFetcher::new(&[(
            frag_url.as_str(),
            "\nrepositories:\n  extended:\n    repository: https://example.com/extended.git\n    directory: ./extended/\n",
        )]);

        let base = format!(
            "\nversion: 2\nextends:\n  - {frag_url}\ncluster:\n  driver: colima\n  network:\n    hostname: test.local\n  colima:\n    memory: 4GiB\n    cores: 2\nrepositories: {{}}\n"
        );
        let (_dir, config_path) = write_test_config(&base);

        let cfg = load_with_fetcher(config_path, &fetcher).expect("load should succeed");
        assert!(cfg.repositories.unwrap().has(&"extended".to_string()));
    }

    // Port of TestLoadCaproniConfig_ExtendsLocalAndRemote.
    #[test]
    fn extends_local_and_remote() {
        let frag_url = format!("{FAKE_SERVER}/caproni.remote.yaml");
        let fetcher = FakeFetcher::new(&[(
            frag_url.as_str(),
            "\nrepositories:\n  remote:\n    repository: https://example.com/remote.git\n    directory: ./remote/\n",
        )]);

        let dir = tempfile::tempdir().unwrap();
        write_fragment(
            dir.path(),
            "caproni.frag.yaml",
            "\nrepositories:\n  local:\n    repository: https://example.com/local.git\n    directory: ./local/\n",
        );

        let config_path = dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            format!(
                "\nversion: 2\nextends:\n  - ./caproni.frag.yaml\n  - {frag_url}\ncluster:\n  driver: colima\n  network:\n    hostname: test.local\n  colima:\n    memory: 4GiB\n    cores: 2\nrepositories: {{}}\n"
            ),
        )
        .unwrap();

        let cfg = load_with_fetcher(config_path.to_string_lossy().into_owned(), &fetcher)
            .expect("load should succeed");
        let repos = cfg.repositories.unwrap();
        assert_eq!(repos.len(), 2);
        assert!(repos.has(&"local".to_string()));
        assert!(repos.has(&"remote".to_string()));
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteMissing_Fails.
    #[test]
    fn extends_remote_missing_fails() {
        let fetcher = FakeFetcher::new(&[]);

        let base = base_config_with_extends(&format!("{FAKE_SERVER}/caproni.missing.yaml"));
        let (_dir, config_path) = write_test_config(&base);

        let err = load_with_fetcher(config_path, &fetcher).expect_err("load should fail");
        assert!(matches!(err, ConfigError::RemoteFragmentFetch(_)));
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteTooLarge_Fails.
    #[test]
    fn extends_remote_too_large_fails() {
        let oversized = "a".repeat((MAX_FRAGMENT_BYTES + 1) as usize);
        let frag_url = format!("{FAKE_SERVER}/caproni.big.yaml");
        let fetcher = FakeFetcher::new(&[(frag_url.as_str(), oversized.as_str())]);

        let base = base_config_with_extends(&frag_url);
        let (_dir, config_path) = write_test_config(&base);

        let err = load_with_fetcher(config_path, &fetcher).expect_err("load should fail");
        assert!(matches!(err, ConfigError::RemoteFragmentFetch(_)));
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteHTTP_Fails. Exercises the
    // real `load_caproni_config` (no injected fetcher): the `https://`-only
    // scheme check rejects a plain `http://` extends: URL before any fetch
    // is attempted, so no fake server is needed.
    #[test]
    fn extends_remote_http_fails() {
        let base = "
version: 2
extends:
  - http://example.com/caproni.frag.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
";
        let (_dir, config_path) = write_test_config(base);

        let gc = GlobalConfig {
            config_file: config_path,
            ..Default::default()
        };
        let err = super::super::caproni::load_caproni_config(&gc).expect_err("load should fail");
        assert!(matches!(err, ConfigError::RemoteFragmentFetch(_)));
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteInvalidName_Fails.
    #[test]
    fn extends_remote_invalid_name_fails() {
        let base = "
version: 2
extends:
  - https://example.com/some-path/gitlab-dev-stack-values.yaml
cluster:
  driver: colima
  network:
    hostname: test.local
  colima:
    memory: 4GiB
    cores: 2
repositories: {}
";
        let (_dir, config_path) = write_test_config(base);

        let gc = GlobalConfig {
            config_file: config_path,
            ..Default::default()
        };
        let err = super::super::caproni::load_caproni_config(&gc).expect_err("load should fail");
        assert!(matches!(err, ConfigError::InvalidFragmentName));
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteHasExtends_Fails.
    #[test]
    fn extends_remote_has_extends_fails() {
        let frag_url = format!("{FAKE_SERVER}/caproni.extended.yaml");
        let fetcher = FakeFetcher::new(&[(
            frag_url.as_str(),
            "\nextends:\n  - ./caproni.nested.yaml\nrepositories: {}\n",
        )]);

        let base = base_config_with_extends(&frag_url);
        let (_dir, config_path) = write_test_config(&base);

        let err = load_with_fetcher(config_path, &fetcher).expect_err("load should fail");
        assert!(matches!(err, ConfigError::FragmentHasExtends));
    }

    // Port of TestValidateProjectFileSchema (table-driven).
    #[test]
    fn validate_project_file_schema_cases() {
        struct Case {
            name: &'static str,
            frag: Value,
            want_err: bool,
        }

        let cases = vec![
            Case {
                name: "valid reloaders only",
                frag: json!({
                    "reloaders": {
                        "web": {
                            "type": "mirror",
                            "repository": "myrepo",
                            "mirror": {
                                "target": {
                                    "namespace": "ns",
                                    "kubernetes_type": "deployment",
                                    "name": "deploy",
                                },
                                "edit_mode_processes": {
                                    "web": {"command": "bin/server"},
                                },
                            },
                        },
                    },
                }),
                want_err: false,
            },
            Case {
                name: "valid lifecycle_hooks only",
                frag: json!({
                    "lifecycle_hooks": [
                        {"type": "edit_mode_start", "script": "./hook.sh"},
                    ],
                }),
                want_err: false,
            },
            Case {
                name: "disallowed top-level key",
                frag: json!({"cluster": {}}),
                want_err: true,
            },
            Case {
                name: "lifecycle_hook missing type",
                frag: json!({
                    "lifecycle_hooks": [{"script": "./hook.sh"}],
                }),
                want_err: true,
            },
            Case {
                name: "lifecycle_hook missing action",
                frag: json!({
                    "lifecycle_hooks": [{"type": "edit_mode_start"}],
                }),
                want_err: true,
            },
            Case {
                name: "lifecycle_hook invalid type value",
                frag: json!({
                    "lifecycle_hooks": [
                        {"type": "not_a_valid_type", "script": "./hook.sh"},
                    ],
                }),
                want_err: true,
            },
        ];

        for case in cases {
            let result = validate_project_file_schema(&case.frag);
            if case.want_err {
                assert!(result.is_err(), "case {:?} should have failed", case.name);
                assert!(
                    matches!(result.unwrap_err(), ConfigError::SchemaValidation(_)),
                    "case {:?} should fail with SchemaValidation",
                    case.name
                );
            } else {
                assert!(
                    result.is_ok(),
                    "case {:?} should have passed: {:?}",
                    case.name,
                    result.unwrap_err()
                );
            }
        }
    }

    // Port of TestValidateRepoDeployersFragment (table-driven).
    #[test]
    fn validate_repo_deployers_fragment_cases() {
        struct Case {
            name: &'static str,
            frag: Value,
            repo_name: &'static str,
            want_err: Option<fn(&ConfigError) -> bool>,
            err_substr: &'static str,
        }

        let cases = vec![
            Case {
                name: "valid fragment",
                repo_name: "myrepo",
                frag: json!({
                    "reloaders": {"web": {"repository": "myrepo"}},
                }),
                want_err: None,
                err_substr: "",
            },
            Case {
                name: "empty fragment",
                repo_name: "myrepo",
                frag: json!({}),
                want_err: None,
                err_substr: "",
            },
            Case {
                name: "reloader references wrong repository",
                repo_name: "myrepo",
                frag: json!({
                    "reloaders": {"web": {"repository": "otherrepo"}},
                }),
                want_err: Some(|e| matches!(e, ConfigError::RepoFragmentWrongRepository { .. })),
                err_substr: "\"otherrepo\"",
            },
            Case {
                name: "reloader missing repository field",
                repo_name: "myrepo",
                frag: json!({
                    "reloaders": {"web": {"type": "mirror"}},
                }),
                want_err: Some(|e| matches!(e, ConfigError::RepoFragmentWrongRepository { .. })),
                err_substr: "\"\"",
            },
        ];

        for case in cases {
            let result = validate_repo_deployers_fragment(&case.frag, case.repo_name);

            match case.want_err {
                None => assert!(result.is_ok(), "case {:?} should have passed", case.name),
                Some(check) => {
                    let err = result.unwrap_err();
                    assert!(
                        check(&err),
                        "case {:?}: unexpected error {err:?}",
                        case.name
                    );
                    if !case.err_substr.is_empty() {
                        assert!(
                            err.to_string().contains(case.err_substr),
                            "case {:?}: error {err} should contain {:?}",
                            case.name,
                            case.err_substr
                        );
                    }
                }
            }
        }
    }

    fn minimal_reloader_yaml(reloader_name: &str, repo_name: &str) -> String {
        format!(
            "
reloaders:
  {reloader_name}:
    type: mirror
    repository: {repo_name}
    mirror:
      target:
        namespace: ns
        kubernetes_type: deployment
        name: deploy
      edit_mode_processes:
        web:
          command: bin/server
"
        )
    }

    fn write_deployers_fragment(dir: &std::path::Path, content: &str) {
        std::fs::write(dir.join("caproni-project.yaml"), content)
            .expect("writing caproni-project.yaml should succeed");
    }

    // xianyun-project.yaml is the primary per-repository fragment
    // filename; caproni-project.yaml is supported as a compatibility
    // alias so existing Go-caproni projects keep working unmodified.
    #[test]
    fn apply_repo_deployers_fragments_prefers_xianyun_project_yaml_over_caproni_alias() {
        let repo_dir = tempfile::tempdir().unwrap();
        std::fs::write(
            repo_dir.path().join("xianyun-project.yaml"),
            minimal_reloader_yaml("primary-reloader", "myrepo"),
        )
        .unwrap();
        std::fs::write(
            repo_dir.path().join("caproni-project.yaml"),
            minimal_reloader_yaml("alias-reloader", "myrepo"),
        )
        .unwrap();

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": repo_dir.path().to_string_lossy(),
                    "edit_mode": true,
                },
            },
        });

        let result = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap();
        let reloaders = result.get("reloaders").and_then(Value::as_object).unwrap();
        assert!(
            reloaders.contains_key("primary-reloader"),
            "xianyun-project.yaml must win over caproni-project.yaml when both exist"
        );
        assert!(!reloaders.contains_key("alias-reloader"));
    }

    #[test]
    fn apply_repo_deployers_fragments_falls_back_to_caproni_project_yaml_alias() {
        let repo_dir = tempfile::tempdir().unwrap();
        write_deployers_fragment(
            repo_dir.path(),
            &minimal_reloader_yaml("alias-only-reloader", "myrepo"),
        );

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": repo_dir.path().to_string_lossy(),
                    "edit_mode": true,
                },
            },
        });

        let result = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap();
        let reloaders = result.get("reloaders").and_then(Value::as_object).unwrap();
        assert!(
            reloaders.contains_key("alias-only-reloader"),
            "caproni-project.yaml must still be found when xianyun-project.yaml is absent"
        );
    }

    // Port of TestApplyRepoDeployersFragments.
    #[test]
    fn apply_repo_deployers_fragments_loads_reloaders_from_edit_mode_repo() {
        let repo_dir = tempfile::tempdir().unwrap();
        write_deployers_fragment(
            repo_dir.path(),
            &minimal_reloader_yaml("my-reloader", "myrepo"),
        );

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": repo_dir.path().to_string_lossy(),
                    "edit_mode": true,
                },
            },
        });

        let result = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap();
        let reloaders = result.get("reloaders").and_then(Value::as_object).unwrap();
        assert!(reloaders.contains_key("my-reloader"));
    }

    #[test]
    fn apply_repo_deployers_fragments_main_config_wins_over_repo_fragment() {
        let repo_dir = tempfile::tempdir().unwrap();
        write_deployers_fragment(
            repo_dir.path(),
            "
reloaders:
  shared:
    type: mirror
    repository: myrepo
    mirror:
      target:
        namespace: from-fragment
        kubernetes_type: deployment
        name: deploy
      edit_mode_processes:
        web:
          command: bin/server
",
        );

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": repo_dir.path().to_string_lossy(),
                    "edit_mode": true,
                },
            },
            "reloaders": {
                "shared": {
                    "type": "mirror",
                    "repository": "myrepo",
                    "mirror": {
                        "target": {
                            "namespace": "from-base",
                            "kubernetes_type": "deployment",
                            "name": "deploy",
                        },
                        "edit_mode_processes": {
                            "web": {"command": "bin/server"},
                        },
                    },
                },
            },
        });

        let result = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap();
        let namespace = &result["reloaders"]["shared"]["mirror"]["target"]["namespace"];
        assert_eq!(namespace, "from-base", "base config must win");
    }

    #[test]
    fn apply_repo_deployers_fragments_skips_repos_without_edit_mode() {
        let repo_dir = tempfile::tempdir().unwrap();
        write_deployers_fragment(
            repo_dir.path(),
            &minimal_reloader_yaml("unwanted", "myrepo"),
        );

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": repo_dir.path().to_string_lossy(),
                },
            },
        });

        let result = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap();
        assert!(result.get("reloaders").is_none());
    }

    #[test]
    fn apply_repo_deployers_fragments_skips_repos_with_missing_directory() {
        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": "/nonexistent/path/that/does/not/exist",
                    "edit_mode": true,
                },
            },
        });

        let result = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap();
        assert!(result.get("reloaders").is_none());
    }

    #[test]
    fn apply_repo_deployers_fragments_noop_when_project_file_absent() {
        let repo_dir = tempfile::tempdir().unwrap();

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": repo_dir.path().to_string_lossy(),
                    "edit_mode": true,
                },
            },
        });

        let result =
            apply_caproni_project(base.clone(), std::path::Path::new("/irrelevant")).unwrap();
        assert_eq!(result, base);
    }

    #[test]
    fn apply_repo_deployers_fragments_resolves_relative_directory_against_config_dir() {
        let config_dir = tempfile::tempdir().unwrap();
        let repo_dir = config_dir.path().join("myrepo");
        std::fs::create_dir_all(&repo_dir).unwrap();
        write_deployers_fragment(&repo_dir, &minimal_reloader_yaml("rel-reloader", "myrepo"));

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": "./myrepo",
                    "edit_mode": true,
                },
            },
        });

        let result = apply_caproni_project(base, config_dir.path()).unwrap();
        let reloaders = result.get("reloaders").and_then(Value::as_object).unwrap();
        assert!(reloaders.contains_key("rel-reloader"));
    }

    #[test]
    fn apply_repo_deployers_fragments_disallowed_top_level_key_errors() {
        let repo_dir = tempfile::tempdir().unwrap();
        write_deployers_fragment(
            repo_dir.path(),
            "
deployers:
  something:
    type: namespace
",
        );

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": repo_dir.path().to_string_lossy(),
                    "edit_mode": true,
                },
            },
        });

        let err = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap_err();
        assert!(matches!(err, ConfigError::SchemaValidation(_)));
    }

    #[test]
    fn apply_repo_deployers_fragments_wrong_repository_errors() {
        let repo_dir = tempfile::tempdir().unwrap();
        write_deployers_fragment(repo_dir.path(), &minimal_reloader_yaml("web", "otherrepo"));

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": repo_dir.path().to_string_lossy(),
                    "edit_mode": true,
                },
            },
        });

        let err = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap_err();
        assert!(matches!(
            err,
            ConfigError::RepoFragmentWrongRepository { .. }
        ));
    }

    #[test]
    fn apply_repo_deployers_fragments_duplicate_reloader_across_repos_errors() {
        let dir_a = tempfile::tempdir().unwrap();
        let dir_b = tempfile::tempdir().unwrap();
        write_deployers_fragment(dir_a.path(), &minimal_reloader_yaml("web", "repo-a"));
        write_deployers_fragment(dir_b.path(), &minimal_reloader_yaml("web", "repo-b"));

        let base = json!({
            "repositories": {
                "repo-a": {
                    "repository": "https://example.com/a.git",
                    "directory": dir_a.path().to_string_lossy(),
                    "edit_mode": true,
                },
                "repo-b": {
                    "repository": "https://example.com/b.git",
                    "directory": dir_b.path().to_string_lossy(),
                    "edit_mode": true,
                },
            },
        });

        let err = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap_err();
        assert!(matches!(err, ConfigError::RepoFragmentDuplicateReloader(_)));
        assert!(err.to_string().contains("\"web\""));
    }

    #[test]
    fn apply_repo_deployers_fragments_lifecycle_hooks_appended_to_repo_hooks() {
        let repo_dir = tempfile::tempdir().unwrap();
        write_deployers_fragment(
            repo_dir.path(),
            "
lifecycle_hooks:
  - type: edit_mode_start
    script: ./project-hook.sh
",
        );

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": repo_dir.path().to_string_lossy(),
                    "edit_mode": true,
                    "lifecycle_hooks": [
                        {"type": "edit_mode_start", "script": "./base-hook.sh"},
                    ],
                },
            },
        });

        let result = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap();
        let hooks = result["repositories"]["myrepo"]["lifecycle_hooks"]
            .as_array()
            .unwrap();
        assert_eq!(hooks.len(), 2);
        assert_eq!(
            hooks[0]["script"], "./base-hook.sh",
            "base hook must be first"
        );
        assert_eq!(
            hooks[1]["script"], "./project-hook.sh",
            "project hook must be appended"
        );
    }

    #[test]
    fn apply_repo_deployers_fragments_lifecycle_hooks_added_when_repo_has_none() {
        let repo_dir = tempfile::tempdir().unwrap();
        write_deployers_fragment(
            repo_dir.path(),
            "
lifecycle_hooks:
  - type: edit_mode_start
    script: ./project-hook.sh
",
        );

        let base = json!({
            "repositories": {
                "myrepo": {
                    "repository": "https://example.com/myrepo.git",
                    "directory": repo_dir.path().to_string_lossy(),
                    "edit_mode": true,
                },
            },
        });

        let result = apply_caproni_project(base, std::path::Path::new("/irrelevant")).unwrap();
        let hooks = result["repositories"]["myrepo"]["lifecycle_hooks"]
            .as_array()
            .unwrap();
        assert_eq!(hooks.len(), 1);
        assert_eq!(hooks[0]["script"], "./project-hook.sh");
    }

    // Port of TestLoadCaproniConfig_ExtendsDuplicateRemoteFragment_Fails.
    #[test]
    fn extends_duplicate_remote_fragment_fails() {
        let frag_url = format!("{FAKE_SERVER}/caproni.extended.yaml");
        let fetcher = FakeFetcher::new(&[(
            frag_url.as_str(),
            "\nrepositories:\n  extended:\n    repository: https://example.com/extended.git\n    directory: ./extended/\n",
        )]);

        let base = format!(
            "\nversion: 2\nextends:\n  - {frag_url}\n  - {frag_url}\ncluster:\n  driver: colima\n  network:\n    hostname: test.local\nrepositories: {{}}\n"
        );
        let (_dir, config_path) = write_test_config(&base);

        let err = load_with_fetcher(config_path, &fetcher).expect_err("load should fail");
        assert!(matches!(err, ConfigError::DuplicateExtends(_)));
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteFragmentDownloadsValuesFile.
    #[test]
    fn extends_remote_fragment_downloads_values_file() {
        const VALUES_CONTENT: &str = "replicaCount: 3\n";

        let frag_url = format!("{FAKE_SERVER}/download/caproni.frag.yaml");
        let values_url = format!("{FAKE_SERVER}/download/values.yaml");
        let fetcher = FakeFetcher::new(&[
            (
                frag_url.as_str(),
                "\ndeployers:\n  gitlab:\n    type: helm\n    helm:\n      namespace: gitlab\n      values_file: values.yaml\n      release:\n        name: gitlab\n        chart: gitlab/gitlab\n",
            ),
            (values_url.as_str(), VALUES_CONTENT),
        ]);

        let base = base_config_with_extends(&frag_url);
        let (_dir, config_path) = write_test_config(&base);

        let cfg = load_with_fetcher(config_path, &fetcher).expect("load should succeed");
        let deployers = cfg.deployers.unwrap();
        let dep = deployers.get(&"gitlab".to_string()).unwrap();
        let helm = dep.helm.as_ref().unwrap();
        assert_ne!(
            helm.values_file, "values.yaml",
            "values_file is rewritten to a local path"
        );
        assert!(std::path::Path::new(&helm.values_file).is_absolute());

        let got = fs::read_to_string(&helm.values_file).unwrap();
        assert_eq!(got, VALUES_CONTENT);
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteFragmentLocalOverride.
    #[test]
    fn extends_remote_fragment_local_override() {
        let frag_url = format!("{FAKE_SERVER}/local-override/caproni.frag.yaml");
        let values_url = format!("{FAKE_SERVER}/local-override/values.yaml");
        let fetcher = FakeFetcher::new(&[
            (
                frag_url.as_str(),
                "\ndeployers:\n  gitlab:\n    type: helm\n    helm:\n      namespace: gitlab\n      values_file: values.yaml\n      release:\n        name: gitlab\n        chart: gitlab/gitlab\n",
            ),
            (values_url.as_str(), "replicaCount: 3\n"),
        ]);

        let dir = tempfile::tempdir().unwrap();
        let local_values = dir.path().join("local-values.yaml");
        fs::write(&local_values, "replicaCount: 5\n").unwrap();

        let config_path = dir.path().join("caproni.yaml");
        fs::write(
            &config_path,
            format!(
                "\nversion: 2\nextends:\n  - {frag_url}\ndeployers:\n  gitlab:\n    type: helm\n    helm:\n      namespace: gitlab\n      values_file: {}\n      release:\n        name: gitlab\n        chart: gitlab/gitlab\ncluster:\n  driver: colima\n  network:\n    hostname: test.local\n  colima:\n    memory: 4GiB\n    cores: 2\nrepositories: {{}}\n",
                local_values.to_string_lossy()
            ),
        )
        .unwrap();

        let cfg = load_with_fetcher(config_path.to_string_lossy().into_owned(), &fetcher)
            .expect("load should succeed");
        let deployers = cfg.deployers.unwrap();
        let dep = deployers.get(&"gitlab".to_string()).unwrap();
        let helm = dep.helm.as_ref().unwrap();
        assert_eq!(
            helm.values_file,
            local_values.to_string_lossy(),
            "local override should be preserved"
        );

        let got = fs::read_to_string(&helm.values_file).unwrap();
        assert_eq!(got, "replicaCount: 5\n");
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteFragmentKustomizeDir_Fails.
    #[test]
    fn extends_remote_fragment_kustomize_dir_fails() {
        let frag_url = format!("{FAKE_SERVER}/caproni.frag.yaml");
        let fetcher = FakeFetcher::new(&[(
            frag_url.as_str(),
            "\ndeployers:\n  gitlab:\n    type: kustomize\n    kustomize:\n      path: ./gitlab\n",
        )]);

        let base = base_config_with_extends(&frag_url);
        let (_dir, config_path) = write_test_config(&base);

        let err = load_with_fetcher(config_path, &fetcher).expect_err("load should fail");
        assert!(matches!(err, ConfigError::RemoteFragmentDirRef), "{err:?}");
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteFragmentKustomizePathOverride
    // (table-driven).
    #[test]
    fn extends_remote_fragment_kustomize_path_override() {
        const FRAGMENT_PATH: &str = "./capronix";
        const LOCAL_OVERLAY: &str = "./local-overlay";
        const REMOTE_TARGET: &str = "https://gitlab.com/org/infra.git//overlays/dev?ref=v1.2.0";

        fn override_for(path: &str) -> String {
            format!(
                "\ndeployers:\n  nix-builder:\n    type: kustomize\n    kustomize:\n      path: {path}\n"
            )
        }

        struct Case {
            name: &'static str,
            base_override: String,
            fragment_override: String,
            local_override: String,
            want_path: &'static str,
            want_err: bool,
        }

        let cases = vec![
            Case {
                name: "base override to local dir",
                base_override: override_for(LOCAL_OVERLAY),
                fragment_override: String::new(),
                local_override: String::new(),
                want_path: LOCAL_OVERLAY,
                want_err: false,
            },
            Case {
                name: "local fragment override to local dir",
                base_override: String::new(),
                fragment_override: override_for(LOCAL_OVERLAY),
                local_override: String::new(),
                want_path: LOCAL_OVERLAY,
                want_err: false,
            },
            Case {
                name: "caproni.local.yaml override to local dir",
                base_override: String::new(),
                fragment_override: String::new(),
                local_override: override_for(LOCAL_OVERLAY),
                want_path: LOCAL_OVERLAY,
                want_err: false,
            },
            Case {
                name: "no override keeps rejecting the fragment's local path",
                base_override: String::new(),
                fragment_override: String::new(),
                local_override: String::new(),
                want_path: "",
                want_err: true,
            },
            Case {
                name: "base override to remote target",
                base_override: override_for(REMOTE_TARGET),
                fragment_override: String::new(),
                local_override: String::new(),
                want_path: REMOTE_TARGET,
                want_err: false,
            },
        ];

        for case in cases {
            let frag_url = format!("{FAKE_SERVER}/caproni.nix-builder.yaml");
            let fragment_body = override_for(FRAGMENT_PATH);
            let fetcher = FakeFetcher::new(&[(frag_url.as_str(), fragment_body.as_str())]);

            let dir = tempfile::tempdir().unwrap();
            fs::create_dir(dir.path().join("local-overlay")).unwrap();

            let mut extends = vec![frag_url.clone()];

            if !case.fragment_override.is_empty() {
                let override_path = dir.path().join("caproni.override.yaml");
                fs::write(&override_path, &case.fragment_override).unwrap();
                extends.push("./caproni.override.yaml".to_string());
            }

            let config_path = dir.path().join("caproni.yaml");
            let base = format!(
                "\nversion: 2\nextends:\n  - {}\ncluster:\n  driver: colima\n  network:\n    hostname: test.local\n  colima:\n    memory: 4GiB\n    cores: 2\nrepositories: {{}}\n{}",
                extends.join("\n  - "),
                case.base_override
            );
            fs::write(&config_path, &base).unwrap();

            if !case.local_override.is_empty() {
                fs::write(
                    dir.path().join("caproni.local.yaml"),
                    format!("version: 2\n{}", case.local_override),
                )
                .unwrap();
            }

            let result = load_with_fetcher(config_path.to_string_lossy().into_owned(), &fetcher);

            if case.want_err {
                let err = result.expect_err(case.name);
                assert!(
                    matches!(err, ConfigError::RemoteFragmentDirRef),
                    "{}: {err:?}",
                    case.name
                );
                continue;
            }

            let cfg = result.unwrap_or_else(|err| panic!("{}: {err:?}", case.name));
            let deployers = cfg.deployers.unwrap();
            let dep = deployers.get(&"nix-builder".to_string()).unwrap();
            let kustomize = dep.kustomize.as_ref().unwrap();
            assert_eq!(kustomize.path, case.want_path, "{}", case.name);
        }
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteFragmentKustomizeBuiltin_Succeeds.
    #[test]
    fn extends_remote_fragment_kustomize_builtin_succeeds() {
        let frag_url = format!("{FAKE_SERVER}/caproni.frag.yaml");
        let fetcher = FakeFetcher::new(&[(
            frag_url.as_str(),
            "\ndeployers:\n  caproni-dev-ca:\n    type: kustomize\n    kustomize:\n      path: builtin:dev-ca\n",
        )]);

        let base = base_config_with_extends(&frag_url);
        let (_dir, config_path) = write_test_config(&base);

        let cfg = load_with_fetcher(config_path, &fetcher).expect("load should succeed");
        let deployers = cfg.deployers.unwrap();
        let dep = deployers.get(&"caproni-dev-ca".to_string()).unwrap();
        assert_eq!(
            dep.kustomize.as_ref().unwrap().path,
            "builtin:dev-ca",
            "a builtin: path must survive untouched"
        );
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteFragmentKustomizeRemoteTarget_Succeeds.
    #[test]
    fn extends_remote_fragment_kustomize_remote_target_succeeds() {
        let frag_url = format!("{FAKE_SERVER}/caproni.frag.yaml");
        let fetcher = FakeFetcher::new(&[(
            frag_url.as_str(),
            "\ndeployers:\n  shared-overlay:\n    type: kustomize\n    kustomize:\n      path: https://gitlab.com/org/infra.git//overlays/dev?ref=v1.2.0\n",
        )]);

        let base = base_config_with_extends(&frag_url);
        let (_dir, config_path) = write_test_config(&base);

        let cfg = load_with_fetcher(config_path, &fetcher).expect("load should succeed");
        let deployers = cfg.deployers.unwrap();
        let dep = deployers.get(&"shared-overlay".to_string()).unwrap();
        assert_eq!(
            dep.kustomize.as_ref().unwrap().path,
            "https://gitlab.com/org/infra.git//overlays/dev?ref=v1.2.0",
            "a remote target must survive untouched"
        );
    }

    // Port of TestLoadCaproniConfig_ExtendsRemoteFragmentMissingValuesFile_Fails.
    #[test]
    fn extends_remote_fragment_missing_values_file_fails() {
        let frag_url = format!("{FAKE_SERVER}/missing-values/caproni.frag.yaml");
        let fetcher = FakeFetcher::new(&[(
            frag_url.as_str(),
            "\ndeployers:\n  gitlab:\n    type: helm\n    helm:\n      namespace: gitlab\n      values_file: values.yaml\n      release:\n        name: gitlab\n        chart: gitlab/gitlab\n",
        )]);

        let base = base_config_with_extends(&frag_url);
        let (_dir, config_path) = write_test_config(&base);

        let err = load_with_fetcher(config_path, &fetcher).expect_err("load should fail");
        assert!(
            err.to_string().contains("values file not found"),
            "unexpected error: {err}"
        );
    }

    // xianyun.local.yaml is the primary local-override filename;
    // caproni.local.yaml is supported as a compatibility alias so
    // existing Go-caproni projects keep working unmodified. When both
    // exist, xianyun.local.yaml wins. See PORT_NOTES.md's
    // naming-migration notes.
    #[test]
    fn load_local_override_prefers_xianyun_local_yaml_over_caproni_local_yaml_alias() {
        let dir = tempfile::tempdir().unwrap();
        let config_path = dir.path().join("xianyun.yaml");
        fs::write(dir.path().join("xianyun.local.yaml"), "primary: true\n").unwrap();
        fs::write(dir.path().join("caproni.local.yaml"), "primary: false\n").unwrap();

        let result = load_local_override(&config_path).unwrap().unwrap();
        assert_eq!(result.get("primary"), Some(&json!(true)));
    }

    #[test]
    fn load_local_override_falls_back_to_caproni_local_yaml_alias() {
        let dir = tempfile::tempdir().unwrap();
        let config_path = dir.path().join("xianyun.yaml");
        fs::write(dir.path().join("caproni.local.yaml"), "alias: true\n").unwrap();

        let result = load_local_override(&config_path).unwrap().unwrap();
        assert_eq!(result.get("alias"), Some(&json!(true)));
    }

    #[test]
    fn load_local_override_returns_none_when_neither_exists() {
        let dir = tempfile::tempdir().unwrap();
        let config_path = dir.path().join("xianyun.yaml");

        assert!(load_local_override(&config_path).unwrap().is_none());
    }
}