termproof 0.4.4

Evidence-first verification for TUI and terminal applications: recipe model, schema, steps, assertions, orchestration, terminal sessions and the evidence pipeline
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
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
//! Validation of recipe values before execution.
//!
//! Validates recipes against the Draft 2020-12 JSON Schema (via `jsonschema`)
//! and adds config-dependent checks (unknown step/assertion names) plus
//! legacy-compatibility carve-outs matching the Python `recipe_schema.py`
//! logic (null tolerance for optional fields, integral-float rejection, path
//! formatting).

use serde_json::Value;
use std::collections::HashSet;

use crate::config::VerifierConfig;
use crate::schema::generate_recipe_schema;

/// Severity of a validation issue.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Severity {
    /// Hard error; recipe must not be executed.
    Error,
    /// Warning; e.g. missing `recipe_version` on legacy recipes.
    Warning,
}

/// A single validation issue with a path and message.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ValidationIssue {
    /// Dotted path to the failing field (e.g. `command.argv`, `steps[0].action`).
    pub path: String,
    /// Human-readable message.
    pub message: String,
    /// Severity.
    pub severity: Severity,
}

impl ValidationIssue {
    /// Create an error-severity issue.
    pub fn error(path: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            path: path.into(),
            message: message.into(),
            severity: Severity::Error,
        }
    }
    /// Create a warning-severity issue.
    pub fn warning(path: impl Into<String>, message: impl Into<String>) -> Self {
        Self {
            path: path.into(),
            message: message.into(),
            severity: Severity::Warning,
        }
    }
}

/// Returns `true` if any issue has `Error` severity.
pub fn has_errors(issues: &[ValidationIssue]) -> bool {
    issues.iter().any(|i| i.severity == Severity::Error)
}

/// Validate a raw recipe value (JSON) before typed deserialization.
///
/// Performs:
/// - `recipe_version` warning if missing, error if not `1`.
/// - JSON Schema validation (Draft 2020-12) with legacy-tolerance suppression.
/// - Legacy integral-float rejection for `cols`, `rows`, `expect_exit_code`.
/// - Unknown plugin name checks from `config`.
pub fn validate_recipe_value(data: &Value, config: &VerifierConfig) -> Vec<ValidationIssue> {
    let mut issues = Vec::new();
    validate_recipe_version(data, &mut issues);
    validate_via_schema(data, &mut issues);
    validate_legacy_int_fields(data, &mut issues);
    validate_plugin_names(data, config, &mut issues);
    issues
}

/// Validate a typed `Recipe` by round-tripping through its JSON value.
pub fn validate_recipe(
    recipe: &crate::recipe::Recipe,
    config: &VerifierConfig,
) -> Vec<ValidationIssue> {
    let value = serde_json::to_value(recipe).expect("recipe serializes");
    validate_recipe_value(&value, config)
}

fn validate_recipe_version(data: &Value, issues: &mut Vec<ValidationIssue>) {
    match data.get("recipe_version") {
        None => {
            issues.push(ValidationIssue::warning(
                "recipe_version",
                "missing recipe_version; treating recipe as legacy v0.x",
            ));
        }
        Some(Value::Number(n)) if n.as_u64() == Some(1) => {}
        Some(Value::Bool(_)) | Some(_) => {
            // Python checks: not int or bool or !=1. Bool is subtype of int
            // in Python, so `true` must be rejected. JSON true is Bool.
            if let Some(Value::Bool(_)) = data.get("recipe_version") {
                issues.push(ValidationIssue::error("recipe_version", "must be 1"));
            } else if !matches!(data.get("recipe_version"), Some(Value::Number(n)) if n.as_u64() == Some(1))
            {
                issues.push(ValidationIssue::error("recipe_version", "must be 1"));
            }
        }
    }
}

fn validate_via_schema(data: &Value, issues: &mut Vec<ValidationIssue>) {
    let schema = generate_recipe_schema();
    // Build a validator for Draft 2020-12.
    let validator = match jsonschema::validator_for(&schema) {
        Ok(v) => v,
        Err(e) => {
            issues.push(ValidationIssue::error("$", format!("invalid schema: {e}")));
            return;
        }
    };
    for error in validator.iter_errors(data) {
        let instance_path = error.instance_path().to_string();
        // Skip recipe_version: handled by validate_recipe_version.
        if instance_path == "/recipe_version" {
            continue;
        }
        // Suppress legacy-tolerated nulls and integral floats owned elsewhere.
        if is_legacy_tolerated(data, &error) {
            continue;
        }
        if is_legacy_int_owned(&error) {
            continue;
        }
        let path = format_instance_path(&error);
        issues.push(ValidationIssue::error(path, error.to_string()));
    }
}

fn format_instance_path(error: &jsonschema::ValidationError<'_>) -> String {
    let path = error.instance_path().to_string();
    if path.is_empty() {
        // Root or missing-required: try to recover property name from message.
        let msg = error.to_string();
        if let Some(prop) = extract_required_property(&msg) {
            return prop;
        }
        return "$".to_string();
    }
    // Convert JSON Pointer `/command/argv` → `command.argv`, `/steps/0/action` → `steps[0].action`
    let parts: Vec<&str> = path.trim_start_matches('/').split('/').collect();
    let mut out = String::new();
    for (i, part) in parts.iter().enumerate() {
        // Decode ~1, ~0 per JSON Pointer.
        let decoded = part.replace("~1", "/").replace("~0", "~");
        let is_index = decoded.chars().all(|c| c.is_ascii_digit()) && !decoded.is_empty();
        if is_index {
            out.push_str(&format!("[{decoded}]"));
        } else if i == 0 {
            out.push_str(&decoded);
        } else {
            // Previous char might be `]` already; then we want `.` before next string.
            out.push('.');
            out.push_str(&decoded);
        }
    }
    if out.is_empty() {
        "$".to_string()
    } else {
        out
    }
}

fn extract_required_property(message: &str) -> Option<String> {
    // jsonschema message like: "Additional properties are not allowed ('foo' was unexpected)" or
    // For required: look for `'prop' is a required property` (Python's jsonschema) but Rust's message differs.
    // Rust jsonschema for required: "Property `name` is required" or similar? Check.
    // We'll handle both forms.
    if let Some(start) = message.find('\'') {
        if let Some(end) = message[start + 1..].find('\'') {
            let prop = &message[start + 1..start + 1 + end];
            if message.contains("required") {
                return Some(prop.to_string());
            }
        }
    }
    // Alternative: backtick form: "Property `name` is required"
    if let Some(start) = message.find('`') {
        if let Some(end) = message[start + 1..].find('`') {
            let prop = &message[start + 1..start + 1 + end];
            if message.contains("required") {
                return Some(prop.to_string());
            }
        }
    }
    None
}

/// Legacy tolerance: inputs the Python legacy validator would have accepted
/// (null for optional fields, unchecked description/intent names) must not
/// become new errors.
fn is_legacy_tolerated(data: &Value, error: &jsonschema::ValidationError<'_>) -> bool {
    let path_str = error.instance_path().to_string();
    if path_str.is_empty() {
        return false;
    }
    // Top-level description/intent: legacy never type-checked them.
    if path_str == "/description" || path_str == "/intent" {
        return true;
    }
    // steps[i].name / assertions[i].name: legacy only checked action/type.
    if (path_str.starts_with("/steps/") || path_str.starts_with("/assertions/"))
        && path_str.ends_with("/name")
    {
        // Count slashes: /steps/0/name => 3 parts. Ensure it's exactly steps[i]/name.
        let parts: Vec<&str> = path_str.split('/').collect();
        if parts.len() == 4 {
            return true;
        }
    }
    // Null tolerance: legacy accepted null for these optional fields.
    let null_tolerant_top: HashSet<&str> = [
        "priority",
        "execution",
        "determinism",
        "timeout_seconds",
        "cols",
        "rows",
        "checks",
        "ci_paths",
        "operator",
        "renderers",
        "description",
        "intent",
    ]
    .into_iter()
    .collect();
    let null_tolerant_command: HashSet<&str> = ["cwd", "pty"].into_iter().collect();
    let null_tolerant_step: HashSet<&str> = ["timeout_seconds"].into_iter().collect();

    // Need to locate value at the error path; if it's not null, not tolerated.
    let value_at = pointer_get(data, &path_str);
    if value_at != Some(&Value::Null) {
        return false;
    }
    // Determine tolerance by path.
    if path_str.matches('/').count() == 1 {
        // Top-level: /priority etc.
        let key = path_str.trim_start_matches('/');
        return null_tolerant_top.contains(key);
    }
    if path_str.starts_with("/command/") && path_str.matches('/').count() == 2 {
        let key = path_str.trim_start_matches("/command/");
        return null_tolerant_command.contains(key);
    }
    if path_str.starts_with("/steps/") {
        let parts: Vec<&str> = path_str.split('/').collect();
        if parts.len() == 4
            && parts[1].chars().all(|c| c.is_ascii_digit())
            && parts[3] == "timeout_seconds"
        {
            return null_tolerant_step.contains("timeout_seconds");
        }
    }
    false
}

fn pointer_get<'a>(data: &'a Value, pointer: &str) -> Option<&'a Value> {
    data.pointer(pointer)
}

/// Suppress schema errors for integer fields owned by explicit legacy checks.
/// JSON Schema draft 2020-12 treats integral floats as `integer`, but the
/// frozen Python validator required actual `int` (`cols: 1.0` must error).
fn is_legacy_int_owned(error: &jsonschema::ValidationError<'_>) -> bool {
    matches!(
        error.instance_path().to_string().as_str(),
        "/cols" | "/rows" | "/expect_exit_code"
    )
}

fn validate_legacy_int_fields(data: &Value, issues: &mut Vec<ValidationIssue>) {
    for key in ["cols", "rows"] {
        if let Some(v) = data.get(key) {
            if !is_valid_positive_int(v) {
                // Only report if value is not null (null is tolerated elsewhere, but we still need int check for non-null floats).
                // For int fields, null is tolerated (so we skip if null).
                if *v != Value::Null {
                    issues.push(ValidationIssue::error(key, "must be a positive integer"));
                }
            }
        }
    }
    if let Some(v) = data.get("expect_exit_code") {
        if *v != Value::Null && !is_valid_int(v) {
            issues.push(ValidationIssue::error(
                "expect_exit_code",
                "must be an integer or null",
            ));
        }
    }
}

fn is_valid_positive_int(v: &Value) -> bool {
    match v {
        Value::Number(n) => {
            if let Some(i) = n.as_u64() {
                i > 0
            } else if let Some(i) = n.as_i64() {
                i > 0
            } else if let Some(f) = n.as_f64() {
                // If it's a float, it's invalid even if integral (e.g. 1.0).
                // Python's `isinstance(1.0, int)` is False, so must error.
                // JSON numbers that are integers but encoded with decimal point are floats.
                // We treat any f64 as invalid for this check; only u64/i64 are valid.
                let _ = f;
                false
            } else {
                false
            }
        }
        Value::Null => true, // handled elsewhere as tolerated
        _ => false,
    }
}

fn is_valid_int(v: &Value) -> bool {
    match v {
        Value::Number(n) => n.is_u64() || n.is_i64(),
        _ => false,
    }
}

fn validate_plugin_names(data: &Value, config: &VerifierConfig, issues: &mut Vec<ValidationIssue>) {
    if let Some(Value::Array(steps)) = data.get("steps") {
        for (i, step) in steps.iter().enumerate() {
            if let Some(Value::Object(map)) = step.as_object().map(|_| step) {
                if let Some(Value::String(action)) = map.get("action") {
                    if !config.steps.contains_key(action) {
                        issues.push(ValidationIssue::error(
                            format!("steps[{i}].action"),
                            format!("unknown step action {action:?}"),
                        ));
                    }
                }
            }
        }
    }
    if let Some(Value::Array(assertions)) = data.get("assertions") {
        for (i, assertion) in assertions.iter().enumerate() {
            if let Some(Value::Object(map)) = assertion.as_object().map(|_| assertion) {
                if let Some(Value::String(kind)) = map.get("type") {
                    if !config.assertions.contains_key(kind) {
                        issues.push(ValidationIssue::error(
                            format!("assertions[{i}].type"),
                            format!("unknown assertion type {kind:?}"),
                        ));
                    }
                }
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    fn cfg() -> VerifierConfig {
        VerifierConfig::builtin()
    }

    #[test]
    fn valid_recipe_has_no_errors() {
        let data = json!({
            "recipe_version": 1,
            "name": "valid",
            "command": {"argv": ["echo", "hi"]},
        });
        let issues = validate_recipe_value(&data, &cfg());
        assert!(!has_errors(&issues));
    }

    #[test]
    fn missing_version_is_warning_only() {
        let data = json!({
            "name": "x",
            "command": {"argv": ["true"]},
        });
        let issues = validate_recipe_value(&data, &cfg());
        assert!(!has_errors(&issues));
        assert!(issues.iter().any(|i| i.severity == Severity::Warning));
    }

    #[test]
    fn unknown_step_is_error() {
        let data = json!({
            "recipe_version": 1,
            "name": "x",
            "command": {"argv": ["true"]},
            "steps": [{"action": "nope"}]
        });
        let issues = validate_recipe_value(&data, &cfg());
        assert!(has_errors(&issues));
    }

    #[test]
    fn integral_float_cols_is_error() {
        let data = json!({
            "recipe_version": 1,
            "name": "x",
            "command": {"argv": ["true"]},
            "cols": 1.0
        });
        let issues = validate_recipe_value(&data, &cfg());
        assert!(has_errors(&issues));
        assert!(issues.iter().any(|i| i.path == "cols"));
    }

    #[test]
    fn null_description_is_tolerated() {
        let data = json!({
            "recipe_version": 1,
            "name": "x",
            "command": {"argv": ["true"]},
            "description": null
        });
        let issues = validate_recipe_value(&data, &cfg());
        assert!(!has_errors(&issues));
    }
}