qa-spec 0.5.0

Core QA specification models and validation utilities.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

use serde_json::{Map, Value};

use crate::{FormSpec, RenderPayload, StoreOp, ValidationResult, build_render_payload, validate};

/// Versioned deterministic plan produced by runner planning functions.
#[derive(Debug, Clone)]
pub struct QaPlanV1 {
    pub plan_version: u16,
    pub form_id: String,
    pub validated_patch: Value,
    pub validation: ValidationResult,
    pub payload: RenderPayload,
    pub effects: Vec<StoreOp>,
    pub warnings: Vec<String>,
    pub errors: Vec<String>,
}

impl QaPlanV1 {
    pub fn is_valid(&self) -> bool {
        self.validation.valid
    }
}

/// Build a deterministic plan for patch submission without applying side effects.
pub fn plan_submit_patch(
    spec: &FormSpec,
    ctx: &Value,
    answers: &Value,
    question_id: &str,
    value: Value,
) -> QaPlanV1 {
    let mut patched = answers.as_object().cloned().unwrap_or_default();
    patched.insert(question_id.to_string(), value);
    build_plan(spec, ctx, Value::Object(patched))
}

/// Build a deterministic plan for submit-all without applying side effects.
pub fn plan_submit_all(spec: &FormSpec, ctx: &Value, answers: &Value) -> QaPlanV1 {
    build_plan(spec, ctx, answers.clone())
}

/// Build a deterministic next-step plan for the current answers/context.
pub fn plan_next(spec: &FormSpec, ctx: &Value, answers: &Value) -> QaPlanV1 {
    build_plan(spec, ctx, normalize_answers(answers))
}

fn build_plan(spec: &FormSpec, ctx: &Value, answers: Value) -> QaPlanV1 {
    let validation = validate(spec, &answers);
    let payload = build_render_payload(spec, ctx, &answers);
    let effects = if validation.valid {
        spec.store.clone()
    } else {
        Vec::new()
    };

    let mut errors = Vec::new();
    if !validation.valid {
        errors.extend(validation.errors.iter().map(|error| {
            format!(
                "{}: {}",
                error.path.clone().unwrap_or_default(),
                error.message
            )
        }));
        errors.extend(
            validation
                .missing_required
                .iter()
                .map(|field| format!("missing required: {}", field)),
        );
        errors.extend(
            validation
                .unknown_fields
                .iter()
                .map(|field| format!("unknown field: {}", field)),
        );
    }

    QaPlanV1 {
        plan_version: 1,
        form_id: spec.id.clone(),
        validated_patch: answers,
        validation,
        payload,
        effects,
        warnings: Vec::new(),
        errors,
    }
}

/// Executes plan effects into the provided store context value.
pub fn execute_plan_effects(
    plan: &QaPlanV1,
    store_ctx: &mut crate::StoreContext,
    secrets_policy: Option<&crate::spec::form::SecretsPolicy>,
    secrets_host_available: bool,
) -> Result<(), crate::StoreError> {
    if !plan.is_valid() {
        return Ok(());
    }
    store_ctx.answers = plan.validated_patch.clone();
    store_ctx.apply_ops(&plan.effects, secrets_policy, secrets_host_available)
}

/// Canonicalize incoming answers into an object payload.
pub fn normalize_answers(answers: &Value) -> Value {
    Value::Object(
        answers
            .as_object()
            .cloned()
            .unwrap_or_else(Map::<String, Value>::new),
    )
}