alopex_sql/distributed_read/
coverage.rs

1//! Rendering of the public v0.8 distributed-read SQL coverage artifacts.
2//!
3//! The row definitions remain in `catalog_v0_8`; this module only renders
4//! them.  Keeping that boundary prevents documentation from expanding the
5//! remotely executable SQL surface.
6
7use serde::Serialize;
8
9use super::catalog_v0_8::{REMOTE_READ_CATALOG_VERSION, RemoteReadCatalogV0_8};
10
11#[derive(Serialize)]
12struct JsonCoverageMatrix<'a> {
13    catalog_version: &'a str,
14    entries: &'a [super::catalog_v0_8::RemoteReadCoverageEntry],
15}
16
17/// Renders the versioned JSON coverage matrix from the closed catalog.
18pub fn render_json() -> String {
19    let entries = RemoteReadCatalogV0_8.coverage_entries();
20    let matrix = JsonCoverageMatrix {
21        catalog_version: REMOTE_READ_CATALOG_VERSION,
22        entries: &entries,
23    };
24    serde_json::to_string_pretty(&matrix)
25        .expect("coverage rows contain only serializable static data")
26        + "\n"
27}
28
29/// Renders the human-readable coverage matrix from the closed catalog.
30pub fn render_markdown() -> String {
31    let entries = RemoteReadCatalogV0_8.coverage_entries();
32    let mut output = format!(
33        "# Alopex v{REMOTE_READ_CATALOG_VERSION} Distributed Read SQL Coverage\n\n\
34This generated matrix is the public contract for cluster-profile reads. `local_only` never means an implicit local fallback.\n\n\
35| ID | Public SQL surface | Remote status | Prerequisite | Normal outcome | Rejection/failure |\n\
36| --- | --- | --- | --- | --- | --- |\n"
37    );
38    for entry in entries {
39        output.push_str(&format!(
40            "| `{}` | {} | `{}` | {} | {} | {} |\n",
41            entry.id,
42            entry.public_surface,
43            serde_json::to_string(&entry.remote_status)
44                .expect("coverage status is serializable")
45                .trim_matches('"'),
46            entry.prerequisite,
47            entry.normal_outcome,
48            entry.failure_outcome,
49        ));
50    }
51    output.push_str(
52        "\nFunction identities are an explicit versioned list in `RemoteReadCatalogV0_8`; adding a local scalar signature does not add remote support.\n",
53    );
54    output
55}
56
57#[cfg(test)]
58mod tests {
59    use std::collections::BTreeSet;
60
61    use super::*;
62    use crate::distributed_read::{
63        REMOTE_DETERMINISTIC_SCALAR_FUNCTIONS, REMOTE_LOCAL_ONLY_SCALAR_FUNCTIONS,
64    };
65    use crate::scalar;
66
67    #[test]
68    fn every_registered_scalar_has_one_explicit_catalog_category() {
69        let catalogued: BTreeSet<_> = REMOTE_DETERMINISTIC_SCALAR_FUNCTIONS
70            .iter()
71            .chain(REMOTE_LOCAL_ONLY_SCALAR_FUNCTIONS)
72            .copied()
73            .collect();
74        let registered: BTreeSet<_> = scalar::signatures()
75            .iter()
76            .map(|signature| signature.name)
77            .collect();
78        assert_eq!(
79            catalogued, registered,
80            "a scalar cannot inherit remote support"
81        );
82    }
83
84    #[test]
85    fn rendered_docs_cover_each_stable_row_once() {
86        let entries = RemoteReadCatalogV0_8.coverage_entries();
87        let ids: BTreeSet<_> = entries.iter().map(|entry| entry.id).collect();
88        assert_eq!(ids.len(), entries.len());
89
90        let json = include_str!("../../../../docs/distributed-read-sql-matrix.json");
91        let markdown = include_str!("../../../../docs/distributed-read.md");
92        for id in ids {
93            assert!(json.contains(id), "JSON is missing {id}");
94            assert!(markdown.contains(id), "Markdown is missing {id}");
95        }
96        assert!(render_json().contains("catalog_version"));
97        assert!(render_markdown().contains("Remote status"));
98    }
99}
alopex_sql/distributed_read/coverage.rs

alopex_sql/distributed_read/
coverage.rs
