Skip to main content

provable_contracts/ontology/extract/
ggplot2_core.rs

1//! PLOT-GG-001 (#6909) — `extract:ggplot2-core`: the ggplot2 usable core as graded `ont:PlotRow` nodes.
2//!
3//! The `entity: {type: ggplot2-core}` contract carries the table (`core_rows:`, one `{row, name, concept, aes}`
4//! per ggplot2 export), the pinned ggplot2 version (`entity.properties.ggplot2`) and the evidence root
5//! (`entity.properties.evidence`); its `entity.ref` is the oracle fixture root. Each row becomes a node typed
6//! `ont:PlotRow` and `ont:<concept>`, joined to four things the tree may hold for it:
7//!
8//! - **contract**: an `entity: {type: ggplot2-row, ref: <row name>}` contract (`plot:contract`);
9//! - **fixture**: an `expected*.json` under `<fixture root>/<row>/` whose `versions.ggplot2` is the pinned one
10//!   (`plot:fixture`; another version is no fixture);
11//! - **surface**: `<evidence>/surface.json` (schema `ggplot2-plot-surface/v1`) listing the row (`plot:reachableBy`);
12//! - **receipt**: a `<evidence>/receipts/*.json` (schema `ggplot2-oracle-receipt/v1`) for the row at the pinned
13//!   version with `passed: true` (`plot:receipt`).
14//!
15//! A row missing any of the four carries `plot:notProven "<row>: <missing, …>"`; the `ggplot2-core` shape says
16//! `maxCount 0` on it. Corpus and positive control call the one [`apply`]. A table whose concept disagrees with
17//! the row's name, a duplicate row, a row contract naming no core row (or one bound twice), and an evidence file
18//! of a foreign schema are refused by name, never guessed.
19
20use std::collections::{BTreeMap, BTreeSet};
21use std::path::Path;
22
23use crate::ontology::rdf::{iri, ont, Graph, Term, ONT_BASE, RDF_TYPE};
24
25use super::claims;
26use super::gguf::ExtractError;
27use super::pv_contract::scalar;
28
29/// The schema a surface snapshot must declare.
30pub const SURFACE_SCHEMA: &str = "ggplot2-plot-surface/v1";
31/// The schema an oracle receipt must declare.
32pub const RECEIPT_SCHEMA: &str = "ggplot2-oracle-receipt/v1";
33
34/// The `plot:` vocabulary: `https://ont.paiml.dev/v1alpha1/plot/<name>`.
35#[must_use]
36pub fn plot(name: &str) -> String {
37    format!("{ONT_BASE}plot/{name}")
38}
39
40/// Name prefix → grammar concept. `labs` and `ggsave` are whole names, the rest are `<prefix>_<…>`.
41const CONCEPTS: [(&str, &str); 10] = [
42    ("geom_", "Geom"),
43    ("stat_", "Stat"),
44    ("position_", "Position"),
45    ("scale_", "Scale"),
46    ("coord_", "Coord"),
47    ("facet_", "Facet"),
48    ("guide_", "Guide"),
49    ("theme_", "Theme"),
50    ("labs", "Label"),
51    ("ggsave", "OutputTarget"),
52];
53
54/// The grammar concept a ggplot2 export's name gives, or `None` for a name outside the grammar.
55#[must_use]
56pub fn concept_of(name: &str) -> Option<&'static str> {
57    CONCEPTS
58        .iter()
59        .find(|(p, _)| match p.strip_suffix('_') {
60            Some(_) => name.len() > p.len() && name.starts_with(p),
61            None => name == *p,
62        })
63        .map(|(_, c)| *c)
64}
65
66/// One row of the table.
67#[derive(Debug, Clone, PartialEq, Eq)]
68pub struct CoreRow {
69    pub row: u64,
70    pub name: String,
71    pub concept: String,
72    pub aes: Vec<String>,
73}
74
75/// What the tree holds for the rows, keyed by row name.
76#[derive(Debug, Clone, Default, PartialEq, Eq)]
77pub struct Evidence {
78    /// row → the stem of the `ggplot2-row` contract bound to it.
79    pub contracts: BTreeMap<String, String>,
80    /// row → the fixture files at the pinned version, repo-relative.
81    pub fixtures: BTreeMap<String, Vec<String>>,
82    /// row → the surface snapshot that lists it.
83    pub surface: BTreeMap<String, String>,
84    /// row → the passing receipts at the pinned version.
85    pub receipts: BTreeMap<String, Vec<String>>,
86}
87
88impl Evidence {
89    /// The items `name` lacks, in proof order.
90    #[must_use]
91    pub fn missing(&self, name: &str) -> Vec<&'static str> {
92        let mut out = Vec::new();
93        if !self.contracts.contains_key(name) {
94            out.push("contract");
95        }
96        if !self.fixtures.contains_key(name) {
97            out.push("fixture");
98        }
99        if !self.surface.contains_key(name) {
100            out.push("surface");
101        }
102        if !self.receipts.contains_key(name) {
103            out.push("receipt");
104        }
105        out
106    }
107}
108
109/// What one extraction found.
110#[derive(Debug, Clone, Default, PartialEq, Eq)]
111pub struct Ggplot2Stats {
112    /// `ggplot2-core` contracts read.
113    pub files_read: usize,
114    /// The pinned ggplot2 version the table declared, when one was read.
115    pub ggplot2: Option<String>,
116    /// The core rows, by name.
117    pub domain: BTreeSet<String>,
118    /// `ggplot2-row` contracts bound to a core row.
119    pub bound: usize,
120    /// Rows with all four proofs.
121    pub proven: BTreeSet<String>,
122    /// Rows without them: every member is a `plot:notProven` edge.
123    pub not_proven: BTreeSet<String>,
124    pub errors: Vec<ExtractError>,
125}
126
127fn refusal(file: &str, what: String) -> ExtractError {
128    ExtractError {
129        file: file.to_string(),
130        what,
131    }
132}
133
134fn one_row(file: &str, v: &serde_yaml::Value) -> Result<CoreRow, ExtractError> {
135    let name =
136        scalar(v.get("name")).ok_or_else(|| refusal(file, "a core row has no name".into()))?;
137    let row = v
138        .get("row")
139        .and_then(serde_yaml::Value::as_u64)
140        .ok_or_else(|| refusal(file, format!("{name}: `row` is not a positive integer")))?;
141    let concept = scalar(v.get("concept")).unwrap_or_default();
142    if concept_of(&name) != Some(concept.as_str()) {
143        return Err(refusal(
144            file,
145            format!(
146                "{name}: concept {concept:?} is not the one its name gives ({:?})",
147                concept_of(&name)
148            ),
149        ));
150    }
151    let aes = scalar(v.get("aes"))
152        .unwrap_or_default()
153        .split(',')
154        .filter(|a| !a.is_empty())
155        .map(str::to_string)
156        .collect();
157    Ok(CoreRow {
158        row,
159        name,
160        concept,
161        aes,
162    })
163}
164
165/// The `core_rows:` table, refused by name on a malformed row, a duplicate name or a duplicate row number.
166pub fn parse_rows(file: &str, doc: &serde_yaml::Value) -> Result<Vec<CoreRow>, ExtractError> {
167    let seq = doc
168        .get("core_rows")
169        .and_then(serde_yaml::Value::as_sequence)
170        .ok_or_else(|| refusal(file, "`core_rows:` is not a list".into()))?;
171    let mut names = BTreeSet::new();
172    let mut numbers = BTreeSet::new();
173    let mut out = Vec::with_capacity(seq.len());
174    for v in seq {
175        let r = one_row(file, v)?;
176        if !names.insert(r.name.clone()) || !numbers.insert(r.row) {
177            return Err(refusal(
178                file,
179                format!("core row {} ({}) is declared twice", r.row, r.name),
180            ));
181        }
182        out.push(r);
183    }
184    Ok(out)
185}
186
187/// Write every row and its evidence into `g`; returns `(proven, not_proven)`. The ONE entry point: the corpus and
188/// the shapes gate's positive control both call it.
189pub fn apply(
190    g: &mut Graph,
191    ggplot2: &str,
192    rows: &[CoreRow],
193    ev: &Evidence,
194) -> (BTreeSet<String>, BTreeSet<String>) {
195    let (mut proven, mut not_proven) = (BTreeSet::new(), BTreeSet::new());
196    for r in rows {
197        let s = iri("plot", &r.name);
198        g.insert(s.clone(), RDF_TYPE, Term::iri(ont("PlotRow")));
199        g.insert(s.clone(), RDF_TYPE, Term::iri(ont(&r.concept)));
200        g.insert(s.clone(), plot("row"), Term::integer(r.row));
201        g.insert(s.clone(), plot("name"), Term::string(&r.name));
202        g.insert(s.clone(), plot("concept"), Term::string(&r.concept));
203        g.insert(s.clone(), plot("ggplot2"), Term::string(ggplot2));
204        for a in &r.aes {
205            g.insert(s.clone(), plot("aes"), Term::string(a));
206        }
207        emit_evidence(g, &s, &r.name, ev);
208        let missing = ev.missing(&r.name);
209        if missing.is_empty() {
210            proven.insert(r.name.clone());
211        } else {
212            let why = format!("{}: {}", r.name, missing.join(", "));
213            g.insert(s, plot("notProven"), Term::string(why));
214            not_proven.insert(r.name.clone());
215        }
216    }
217    (proven, not_proven)
218}
219
220fn emit_evidence(g: &mut Graph, s: &str, name: &str, ev: &Evidence) {
221    if let Some(c) = ev.contracts.get(name) {
222        g.insert(s.to_string(), plot("contract"), Term::string(c));
223    }
224    for f in ev.fixtures.get(name).into_iter().flatten() {
225        g.insert(s.to_string(), plot("fixture"), Term::string(f));
226    }
227    if let Some(f) = ev.surface.get(name) {
228        g.insert(s.to_string(), plot("reachableBy"), Term::string(f));
229    }
230    for f in ev.receipts.get(name).into_iter().flatten() {
231        g.insert(s.to_string(), plot("receipt"), Term::string(f));
232    }
233}
234
235/// Bind every `ggplot2-row` contract to its core row; one naming no row, or a row bound twice, is refused.
236fn bind_contracts(
237    contract_dir: &Path,
238    domain: &BTreeSet<String>,
239    stats: &mut Ggplot2Stats,
240) -> BTreeMap<String, String> {
241    let mut out = BTreeMap::new();
242    for (stem, r, _) in claims::entity_docs(contract_dir, "ggplot2-row") {
243        if !domain.contains(&r) {
244            stats.errors.push(refusal(
245                &stem,
246                format!("ggplot2-row ref {r:?} names no core row"),
247            ));
248        } else if let Some(prev) = out.insert(r.clone(), stem.clone()) {
249            stats.errors.push(refusal(
250                &stem,
251                format!("core row {r} is already bound to {prev}"),
252            ));
253        }
254    }
255    stats.bound = out.len();
256    out
257}
258
259fn read_json(path: &Path) -> Option<serde_json::Value> {
260    serde_json::from_slice(&std::fs::read(path).ok()?).ok()
261}
262
263/// The fixtures at `version` under `<root>/<fixtures>/<row>/expected*.json`, repo-relative and sorted.
264#[must_use]
265pub fn fixtures_at(root: &Path, fixtures: &str, row: &str, version: &str) -> Vec<String> {
266    let dir = root.join(fixtures).join(row);
267    let Ok(entries) = std::fs::read_dir(&dir) else {
268        return Vec::new();
269    };
270    let mut out: Vec<String> = entries
271        .filter_map(Result::ok)
272        .map(|e| e.file_name().to_string_lossy().into_owned())
273        .filter(|n| n.starts_with("expected") && n.ends_with(".json"))
274        .filter(|n| {
275            read_json(&dir.join(n)).is_some_and(|j| {
276                j.pointer("/versions/ggplot2")
277                    .and_then(serde_json::Value::as_str)
278                    == Some(version)
279            })
280        })
281        .map(|n| format!("{fixtures}/{row}/{n}"))
282        .collect();
283    out.sort();
284    out
285}
286
287/// The schema check every evidence file passes first: a foreign schema is refused naming the file.
288fn schema_is(rel: &str, j: &serde_json::Value, want: &str) -> Result<(), ExtractError> {
289    match j.get("schema").and_then(serde_json::Value::as_str) {
290        Some(s) if s == want => Ok(()),
291        other => Err(refusal(
292            rel,
293            format!("schema {other:?} is not {want} — refused by name"),
294        )),
295    }
296}
297
298/// `<evidence>/surface.json`: the rows it lists, each mapped to the snapshot. Absent is no surface, not an error.
299pub fn read_surface(
300    root: &Path,
301    evidence: &str,
302    domain: &BTreeSet<String>,
303) -> Result<BTreeMap<String, String>, ExtractError> {
304    let rel = format!("{evidence}/surface.json");
305    let path = root.join(&rel);
306    if !path.exists() {
307        return Ok(BTreeMap::new());
308    }
309    let j = read_json(&path).ok_or_else(|| refusal(&rel, "not JSON".into()))?;
310    schema_is(&rel, &j, SURFACE_SCHEMA)?;
311    let rows = j
312        .get("rows")
313        .and_then(serde_json::Value::as_array)
314        .ok_or_else(|| refusal(&rel, "`rows` is not a list".into()))?;
315    let mut out = BTreeMap::new();
316    for r in rows.iter().filter_map(serde_json::Value::as_str) {
317        if !domain.contains(r) {
318            return Err(refusal(&rel, format!("lists {r:?}, which is no core row")));
319        }
320        out.insert(r.to_string(), rel.clone());
321    }
322    Ok(out)
323}
324
325/// One receipt: `Some(row)` when it passed at `version`, `None` when it did not; refused on a foreign schema or
326/// a row outside the domain.
327pub fn receipt_row(
328    rel: &str,
329    j: &serde_json::Value,
330    version: &str,
331    domain: &BTreeSet<String>,
332) -> Result<Option<String>, ExtractError> {
333    schema_is(rel, j, RECEIPT_SCHEMA)?;
334    let row = j
335        .get("row")
336        .and_then(serde_json::Value::as_str)
337        .unwrap_or_default();
338    if !domain.contains(row) {
339        return Err(refusal(rel, format!("receipt row {row:?} is no core row")));
340    }
341    let at = j.get("ggplot2").and_then(serde_json::Value::as_str) == Some(version);
342    let passed = j.get("passed").and_then(serde_json::Value::as_bool) == Some(true);
343    Ok((at && passed).then(|| row.to_string()))
344}
345
346/// Every `<evidence>/receipts/*.json`; a refused file is pushed onto `errors` and contributes nothing.
347fn read_receipts(
348    root: &Path,
349    evidence: &str,
350    version: &str,
351    domain: &BTreeSet<String>,
352    errors: &mut Vec<ExtractError>,
353) -> BTreeMap<String, Vec<String>> {
354    let dir = format!("{evidence}/receipts");
355    let mut names: Vec<String> = std::fs::read_dir(root.join(&dir))
356        .into_iter()
357        .flatten()
358        .filter_map(Result::ok)
359        .map(|e| e.file_name().to_string_lossy().into_owned())
360        .filter(|n| n.ends_with(".json"))
361        .collect();
362    names.sort();
363    let mut out: BTreeMap<String, Vec<String>> = BTreeMap::new();
364    for n in names {
365        let rel = format!("{dir}/{n}");
366        let got = read_json(&root.join(&rel))
367            .ok_or_else(|| refusal(&rel, "not JSON".into()))
368            .and_then(|j| receipt_row(&rel, &j, version, domain));
369        match got {
370            Ok(Some(row)) => out.entry(row).or_default().push(rel),
371            Ok(None) => {}
372            Err(e) => errors.push(e),
373        }
374    }
375    out
376}
377
378fn property(doc: &serde_yaml::Value, key: &str) -> Option<String> {
379    scalar(
380        doc.get("entity")
381            .and_then(|e| e.get("properties"))
382            .and_then(|p| p.get(key)),
383    )
384}
385
386/// One `ggplot2-core` contract into `g`.
387fn extract_one(
388    contract_dir: &Path,
389    stem: &str,
390    fixtures: &str,
391    doc: &serde_yaml::Value,
392    g: &mut Graph,
393    stats: &mut Ggplot2Stats,
394) -> Result<(), ExtractError> {
395    let root = super::repo_root(contract_dir);
396    let version = property(doc, "ggplot2").ok_or_else(|| {
397        refusal(
398            stem,
399            "entity.properties.ggplot2 (the pinned version) is missing".into(),
400        )
401    })?;
402    let evidence = property(doc, "evidence").ok_or_else(|| {
403        refusal(
404            stem,
405            "entity.properties.evidence (the evidence root) is missing".into(),
406        )
407    })?;
408    let rows = parse_rows(stem, doc)?;
409    let domain: BTreeSet<String> = rows.iter().map(|r| r.name.clone()).collect();
410    let ev = Evidence {
411        contracts: bind_contracts(contract_dir, &domain, stats),
412        fixtures: rows
413            .iter()
414            .map(|r| {
415                (
416                    r.name.clone(),
417                    fixtures_at(&root, fixtures, &r.name, &version),
418                )
419            })
420            .filter(|(_, f)| !f.is_empty())
421            .collect(),
422        surface: read_surface(&root, &evidence, &domain)?,
423        receipts: read_receipts(&root, &evidence, &version, &domain, &mut stats.errors),
424    };
425    let (proven, not_proven) = apply(g, &version, &rows, &ev);
426    stats.ggplot2 = Some(version);
427    stats.domain.extend(domain);
428    stats.proven.extend(proven);
429    stats.not_proven.extend(not_proven);
430    stats.files_read += 1;
431    Ok(())
432}
433
434/// Every `entity: {type: ggplot2-core}` contract under `contract_dir`.
435pub fn extract(contract_dir: &Path, g: &mut Graph) -> Ggplot2Stats {
436    let mut stats = Ggplot2Stats::default();
437    for (stem, fixtures, doc) in claims::entity_docs(contract_dir, "ggplot2-core") {
438        if let Err(e) = extract_one(contract_dir, &stem, &fixtures, &doc, g, &mut stats) {
439            stats.errors.push(e);
440        }
441    }
442    stats
443}
444
445/// The positive control (R-3): a table row whose concept disagrees with its name is refused, and the same table
446/// with the right concept is not — every run, in memory.
447#[must_use]
448pub fn positive_control() -> bool {
449    let doc = |concept: &str| -> serde_yaml::Value {
450        serde_yaml::from_str(&format!(
451            "core_rows:\n  - {{row: 1, name: geom_point, concept: {concept}, aes: \"x,y\"}}\n"
452        ))
453        .unwrap_or_default()
454    };
455    let refused = parse_rows("pc", &doc("Stat"))
456        .is_err_and(|e| e.what.contains("is not the one its name gives"));
457    refused && parse_rows("pc", &doc("Geom")).is_ok_and(|r| r.len() == 1)
458}
459
460#[cfg(test)]
461#[path = "ggplot2_core_tests.rs"]
462mod tests;