kshana 0.23.0

Open, reproducible PNT-resilience simulator with quantum-sensor performance models
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

// SPDX-License-Identifier: AGPL-3.0-only
//! `validation_report` — emit a one-page, self-contained HTML validation summary.
//!
//! This collates Kshana's headline validation facts into a single print-ready page (a print
//! stylesheet makes a clean PDF via any headless browser, with no LaTeX or other heavy
//! dependency). It is driven directly by the verification matrix
//! (`src/verification.rs::verification_matrix()`) — the SAME single source the kshana.dev
//! ledger and the generated docs come from — so it can never drift from the code: every
//! externally-validated row is listed with the module it lives in, the **test that enforces
//! it in CI** and the **external oracle** it is checked against. Run it as
//! `validation_report [out.html]` (defaults to stdout); the release workflow generates
//! `kshana-validation-summary.html` and attaches it to the tagged release.
//!
//! Honest scope: this summarises *what the suite already asserts* — it does not itself re-run
//! the physics. The authority is the cited test; if a test is removed or weakened, that is a
//! code review concern, not something this page can detect.

use kshana::verification::{verification_matrix, VerificationItem, VerificationStatus};
use std::io::Write;

/// The first repo-relative `tests/…` or `src/…` path mentioned in a free-text field,
/// for the compact "enforced by" cell; falls back to the module name.
fn primary_evidence(it: &VerificationItem) -> String {
    for raw in it
        .tests
        .split(|c: char| c.is_whitespace() || c == ',' || c == ';' || c == '(' || c == ')')
    {
        let tok = raw.trim();
        if tok.ends_with(".rs") && (tok.starts_with("tests/") || tok.starts_with("src/")) {
            return tok.to_string();
        }
    }
    if it.tests.contains("::") {
        // an in-module unit test such as `navsignal::code_tests`
        if let Some(first) = it.tests.split_whitespace().next() {
            return first.to_string();
        }
    }
    if !it.module.is_empty() {
        return format!("module: {}", it.module);
    }
    "—".to_string()
}

/// Build the self-contained validation-summary HTML for `version` from the matrix.
fn render(version: &str, items: &[VerificationItem]) -> String {
    let validated: Vec<&VerificationItem> = items
        .iter()
        .filter(|i| i.status == VerificationStatus::Validated)
        .collect();
    let mut h = String::new();
    h.push_str("<!DOCTYPE html>\n<html lang=\"en\"><head><meta charset=\"utf-8\">\n");
    h.push_str("<title>Kshana validation summary</title>\n<style>\n");
    h.push_str(
        "body{font:14px/1.5 -apple-system,Segoe UI,Roboto,sans-serif;color:#1a1a1a;\
         max-width:64rem;margin:2rem auto;padding:0 1rem}\
         h1{font-size:1.5rem;margin:0 0 .25rem}.sub{color:#555;margin:0 0 1.5rem}\
         table{border-collapse:collapse;width:100%}th,td{border:1px solid #ddd;\
         padding:.5rem .6rem;text-align:left;vertical-align:top}\
         th{background:#f5f3ee}code{font-size:.85em}.ok{color:#1a7f37;font-weight:600}\
         footer{margin-top:1.5rem;color:#777;font-size:.85em}\
         @media print{body{margin:0;max-width:none}a{color:inherit;text-decoration:none}}\n",
    );
    h.push_str("</style></head><body>\n");
    h.push_str(&format!(
        "<h1>Kshana validation summary <span class=\"ok\">{version}</span></h1>\n"
    ));
    h.push_str(&format!(
        "<p class=\"sub\">The {} externally-validated capabilities, generated from the \
         verification matrix. Every row is enforced by a test in continuous integration and \
         checked against an external, authoritative oracle. This page indexes the validation \
         suite; the cited test is the source of truth. The full {}-row matrix (incl. the \
         honestly-Modelled and partner-owned rows) is at docs/VERIFICATION-MATRIX.md and on \
         kshana.dev.</p>\n",
        validated.len(),
        items.len(),
    ));
    h.push_str(
        "<table>\n<thead><tr><th>Capability</th><th>What it does</th><th>Enforced by</th>\
                <th>External oracle</th></tr></thead>\n<tbody>\n",
    );
    for it in &validated {
        h.push_str(&format!(
            "<tr><td class=\"ok\">{}</td><td>{}</td><td><code>{}</code></td><td>{}</td></tr>\n",
            esc(it.requirement),
            esc(it.capability),
            esc(&primary_evidence(it)),
            esc(it.oracle),
        ));
    }
    h.push_str("</tbody></table>\n");
    h.push_str(
        "<footer>Generated by <code>validation_report</code> from \
         <code>verification_matrix()</code> — the same single source as the kshana.dev ledger \
         and docs/VERIFICATION-MATRIX.md. Honest scope: this summarises what the suite asserts; \
         it does not itself re-run the physics. See docs/VALIDATION.md and \
         docs/CLAIMS-VS-REALITY.md.</footer>\n",
    );
    h.push_str("</body></html>\n");
    h
}

/// Minimal HTML-text escaping for the table cells.
fn esc(s: &str) -> String {
    s.replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
}

fn main() -> std::io::Result<()> {
    let html = render(env!("CARGO_PKG_VERSION"), &verification_matrix());
    match std::env::args().nth(1) {
        Some(path) => {
            let mut f = std::fs::File::create(&path)?;
            f.write_all(html.as_bytes())?;
            eprintln!("wrote validation summary to {path}");
        }
        None => {
            print!("{html}");
        }
    }
    Ok(())
}

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

    #[test]
    fn report_is_well_formed_and_lists_every_validated_capability() {
        let m = verification_matrix();
        let h = render("v9.9.9", &m);
        assert!(h.starts_with("<!DOCTYPE html>"));
        assert!(h.trim_end().ends_with("</html>"));
        assert!(h.contains("v9.9.9"));
        // Every externally-validated row and its enforcing evidence must appear.
        for it in m
            .iter()
            .filter(|i| i.status == VerificationStatus::Validated)
        {
            assert!(
                h.contains(&esc(it.requirement)),
                "missing validated capability {}",
                it.requirement
            );
            assert!(
                h.contains(&esc(&primary_evidence(it))),
                "missing evidence for {}",
                it.requirement
            );
        }
        // Honest-scope disclaimer must be present (no overclaim).
        assert!(h.to_lowercase().contains("does not itself re-run"));
    }

    #[test]
    fn primary_evidence_prefers_a_real_test_path() {
        let m = verification_matrix();
        // At least most validated rows resolve to a concrete tests/ or src/ path.
        let with_path = m
            .iter()
            .filter(|i| i.status == VerificationStatus::Validated)
            .filter(|i| {
                let p = primary_evidence(i);
                p.starts_with("tests/") || p.starts_with("src/")
            })
            .count();
        assert!(
            with_path >= 25,
            "too few validated rows resolve to a file path: {with_path}"
        );
    }

    #[test]
    fn html_escaping_neutralises_markup() {
        assert_eq!(esc("a<b>&c"), "a&lt;b&gt;&amp;c");
    }
}