dtcs 0.3.0

//! Python bindings exposed through maturin as `dtcs._native`.

use pyo3::exceptions::{PyTypeError, PyValueError};
use pyo3::prelude::*;
use pyo3::types::{PyByteArray, PyDict};
use serde::Serialize;

use crate::compatibility::{analyze as analyze_compatibility, analyze_evolution, ComparisonScope};
use crate::diagnostics::inspect_contract;
use crate::lineage::analyze_with_options;
use crate::model::TransformationContract;
use crate::parser::{parse, parse_file, DocumentFormat, ParseResult};

fn value_to_py(py: Python<'_>, value: &impl Serialize) -> PyResult<Py<PyAny>> {
    let json = serde_json::to_string(value)
        .map_err(|e| PyValueError::new_err(format!("serialization failed: {e}")))?;
    let json_mod = py.import("json")?;
    json_mod
        .call_method1("loads", (json,))
        .map(|obj| obj.unbind())
}

fn parse_format(format: &str) -> PyResult<DocumentFormat> {
    match format.to_lowercase().as_str() {
        "yaml" | "yml" => Ok(DocumentFormat::Yaml),
        "json" => Ok(DocumentFormat::Json),
        other => Err(PyValueError::new_err(format!(
            "unsupported format '{other}'; use 'yaml' or 'json'"
        ))),
    }
}

fn content_to_bytes(content: &Bound<'_, PyAny>) -> PyResult<Vec<u8>> {
    if content.is_none() {
        return Err(PyTypeError::new_err("content must be str or bytes"));
    }
    if let Ok(text) = content.extract::<String>() {
        return Ok(text.into_bytes());
    }
    if let Ok(data) = content.extract::<Vec<u8>>() {
        return Ok(data);
    }
    if let Ok(byte_array) = content.downcast::<PyByteArray>() {
        return Ok(unsafe { byte_array.as_bytes().to_vec() });
    }
    Err(PyTypeError::new_err(
        "content must be str, bytes, or bytearray",
    ))
}

fn contract_from_py(
    py: Python<'_>,
    contract: &Bound<'_, PyAny>,
) -> PyResult<TransformationContract> {
    if contract.is_none() {
        return Err(PyTypeError::new_err("contract must be a dict, not None"));
    }
    let json_mod = py.import("json")?;
    let json_str: String = json_mod
        .call_method(
            "dumps",
            (contract,),
            Some(&{
                let kwargs = PyDict::new(py);
                kwargs.set_item("allow_nan", false)?;
                kwargs
            }),
        )
        .map_err(|_| {
            PyValueError::new_err("contract contains non-finite float values (NaN or Infinity)")
        })?
        .extract()?;
    serde_json::from_str(&json_str).map_err(|e| contract_deserialize_error(&e.to_string()))
}

fn contract_deserialize_error(message: &str) -> PyErr {
    if message.contains("unknown field") && message.contains('_') {
        return PyValueError::new_err(format!(
            "invalid contract: {message}. DTCS contracts use camelCase keys (for example dtcsVersion, semanticActions)"
        ));
    }
    PyValueError::new_err(format!("invalid contract: {message}"))
}

fn parse_result_to_py(py: Python<'_>, result: ParseResult) -> PyResult<Py<PyAny>> {
    let dict = PyDict::new(py);
    match result.contract {
        Some(contract) => dict.set_item("contract", value_to_py(py, &contract)?)?,
        None => dict.set_item("contract", py.None())?,
    }
    dict.set_item("report", value_to_py(py, &result.report)?)?;
    Ok(dict.into())
}

/// DTCS specification version this crate targets.
#[pyfunction]
fn spec_version() -> &'static str {
    crate::SPEC_VERSION
}

/// Parse a DTCS document from text or bytes.
#[pyfunction]
#[pyo3(signature = (content, format="yaml"))]
fn parse_document(py: Python<'_>, content: &Bound<'_, PyAny>, format: &str) -> PyResult<Py<PyAny>> {
    let bytes = content_to_bytes(content)?;
    let doc_format = parse_format(format)?;
    parse_result_to_py(py, parse(&bytes, doc_format))
}

/// Parse a DTCS document from a file path.
#[pyfunction]
fn parse_path(py: Python<'_>, path: &str) -> PyResult<Py<PyAny>> {
    let result = parse_file(path).map_err(|e| PyValueError::new_err(e.to_string()))?;
    parse_result_to_py(py, result)
}

/// Validate a parsed transformation contract.
#[pyfunction]
fn validate_contract(py: Python<'_>, contract: &Bound<'_, PyAny>) -> PyResult<Py<PyAny>> {
    let contract = contract_from_py(py, contract)?;
    value_to_py(py, &crate::validate(&contract))
}

/// Parse and validate a DTCS document in one step.
#[pyfunction]
#[pyo3(signature = (content, format="yaml"))]
fn validate_document(
    py: Python<'_>,
    content: &Bound<'_, PyAny>,
    format: &str,
) -> PyResult<Py<PyAny>> {
    let bytes = content_to_bytes(content)?;
    let doc_format = parse_format(format)?;
    value_to_py(py, &crate::parse_and_validate(&bytes, doc_format))
}

/// Validate metadata for a parsed transformation contract.
#[pyfunction]
fn metadata_validate(py: Python<'_>, contract: &Bound<'_, PyAny>) -> PyResult<Py<PyAny>> {
    let contract = contract_from_py(py, contract)?;
    value_to_py(py, &crate::metadata::validate(&contract))
}

/// Return a short human-readable contract summary.
#[pyfunction]
fn inspect(py: Python<'_>, contract: &Bound<'_, PyAny>) -> PyResult<String> {
    let contract = contract_from_py(py, contract)?;
    Ok(inspect_contract(&contract))
}

/// Analyze compatibility between two contracts.
#[pyfunction]
#[pyo3(signature = (source, target, scope=None))]
fn compat_analyze(
    py: Python<'_>,
    source: &Bound<'_, PyAny>,
    target: &Bound<'_, PyAny>,
    scope: Option<Vec<String>>,
) -> PyResult<Py<PyAny>> {
    let source = contract_from_py(py, source)?;
    let target = contract_from_py(py, target)?;
    let scope = ComparisonScope::from_tokens(&scope.unwrap_or_default()).map_err(|invalid| {
        PyValueError::new_err(format!("invalid scope token(s): {}", invalid.join(", ")))
    })?;
    value_to_py(py, &analyze_compatibility(&source, &target, scope))
}

/// Analyze evolution between two contract revisions.
#[pyfunction]
fn evolve_analyze(
    py: Python<'_>,
    older: &Bound<'_, PyAny>,
    newer: &Bound<'_, PyAny>,
) -> PyResult<Py<PyAny>> {
    let older = contract_from_py(py, older)?;
    let newer = contract_from_py(py, newer)?;
    value_to_py(py, &analyze_evolution(&older, &newer))
}

/// Analyze lineage for a contract.
#[pyfunction]
#[pyo3(signature = (contract, impact=None, dependency=None))]
fn lineage_analyze(
    py: Python<'_>,
    contract: &Bound<'_, PyAny>,
    impact: Option<String>,
    dependency: Option<String>,
) -> PyResult<Py<PyAny>> {
    let contract = contract_from_py(py, contract)?;
    value_to_py(
        py,
        &analyze_with_options(&contract, impact.as_deref(), dependency.as_deref()),
    )
}

/// Validate version identifiers on a contract.
#[pyfunction]
fn version_validate(py: Python<'_>, contract: &Bound<'_, PyAny>) -> PyResult<Py<PyAny>> {
    let contract = contract_from_py(py, contract)?;
    value_to_py(py, &crate::versioning::validate(&contract))
}

/// Native extension module for the Python `dtcs` package.
#[pymodule]
fn _native(m: &Bound<'_, PyModule>) -> PyResult<()> {
    m.add_function(wrap_pyfunction!(spec_version, m)?)?;
    m.add_function(wrap_pyfunction!(parse_document, m)?)?;
    m.add_function(wrap_pyfunction!(parse_path, m)?)?;
    m.add_function(wrap_pyfunction!(validate_contract, m)?)?;
    m.add_function(wrap_pyfunction!(metadata_validate, m)?)?;
    m.add_function(wrap_pyfunction!(validate_document, m)?)?;
    m.add_function(wrap_pyfunction!(inspect, m)?)?;
    m.add_function(wrap_pyfunction!(compat_analyze, m)?)?;
    m.add_function(wrap_pyfunction!(evolve_analyze, m)?)?;
    m.add_function(wrap_pyfunction!(lineage_analyze, m)?)?;
    m.add_function(wrap_pyfunction!(version_validate, m)?)?;
    Ok(())
}