qubit-validator 0.1.0

// =============================================================================
//    Copyright (c) 2025 - 2026 Haixing Hu.
//
//    SPDX-License-Identifier: Apache-2.0
//
//    Licensed under the Apache License, Version 2.0.
// =============================================================================

//! Adapter from text validators that consume dependency context.

use std::error::Error;
use std::sync::Arc;

use super::BoundValidationContext;
use super::DependencySpec;
use super::PreparedValidator;
use super::internal::ContextualTextValidatorAdapter;
use crate::Validator;
use crate::ViolationDraft;

/// Prepares a text validator that reads its declared dependency slots.
///
/// The adapter passes the supplied [`BoundValidationContext`] directly to the
/// typed validator. When execution goes through [`super::BoundValidator`],
/// that boundary checks dependency count, shape, optionality, and paths before
/// invoking the adapter. The returned adapter does not validate the declared
/// dependency contract itself. Callers invoking [`PreparedValidator::validate`]
/// directly must supply a context satisfying
/// [`PreparedValidator::dependency_specs`]. Domain errors are converted with
/// `map_error`; callers must keep raw input out of the resulting draft.
///
/// # Type Parameters
///
/// - `V`: Text validator implementing the context-aware [`Validator`] contract.
/// - `E`: Its static domain error type, created and mapped within the
///   synchronous call, so it need not be `Send` or `Sync`.
/// - `M`: Mapper from the domain error to a safe violation draft.
///
/// # Panics
///
/// This function does not panic. A non-text erased input is returned as an
/// execution error by the prepared adapter.
///
/// # Parameters
///
/// - `dependencies`: Static dependency slots declared in execution order.
/// - `validator`: Thread-safe validator invoked with checked text and context.
/// - `map_error`: Converts a domain error to safe violation metadata.
///
/// # Returns
///
/// A shared prepared adapter for the supplied validator and mapper.
#[must_use]
pub fn prepare_contextual_text_validator<V, E, M>(
    dependencies: &'static [DependencySpec],
    validator: V,
    map_error: M,
) -> Arc<dyn PreparedValidator>
where
    V: for<'a> Validator<str, BoundValidationContext<'a>, Error = E> + Send + Sync + 'static,
    E: Error + 'static,
    M: Fn(E) -> ViolationDraft + Send + Sync + 'static,
{
    Arc::new(ContextualTextValidatorAdapter::new(validator, map_error, dependencies))
}