sbol2 1.1.0

Rust implementation of the SBOL 2.3.0 specification: typed data model, RDF I/O, and validation.
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
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
//! Render `docs/sbol2-conformance.md` from the SBOL 2 validation rule
//! catalog. This is the SBOL 2 peer of `sbol3::render_conformance_report`:
//! it enumerates the generated 268-rule catalog by status, gate, and
//! configuration axis, records the SBOLTestSuite corpus outcomes and the
//! validation-flag model, and states the cross-implementation agreement
//! against libSBOLj.

use crate::validation::{
    Blocker, NormativeSeverity, RuleStatus, VALIDATION_RULE_SPEC_PATH,
    VALIDATION_RULE_SPEC_VERSION, ValidationGate, ValidationRuleStatus,
};

/// Renders the SBOL 2 conformance report markdown for the supplied rule
/// catalog. Pass `validation_rule_statuses()` to render the canonical
/// committed report.
pub fn render_sbol2_conformance_report(statuses: &[ValidationRuleStatus]) -> String {
    let mut out = String::new();
    render_header(&mut out);
    render_headline_coverage(&mut out, statuses);
    render_status_taxonomy(&mut out, statuses);
    render_gate_model(&mut out, statuses);
    render_configurable_section(&mut out, statuses);
    render_machine_uncheckable_section(&mut out, statuses);
    render_corpus_results(&mut out);
    render_cross_impl(&mut out);
    render_per_status_section(
        &mut out,
        statuses,
        RuleStatus::Error,
        "Error",
        "Algorithm complete; MUST violations emit as `Severity::Error`.",
    );
    render_per_status_section(
        &mut out,
        statuses,
        RuleStatus::Warning,
        "Warning",
        "Algorithm complete; SHOULD violations emit as `Severity::Warning`.",
    );
    out
}

fn render_header(out: &mut String) {
    out.push_str("# SBOL 2.3.0 Conformance Report\n\n");
    out.push_str(
        "This file is generated by `cargo run -p sbol2 --bin generate-sbol2-conformance-report`.\n",
    );
    out.push_str(
        "It is committed and CI runs `git diff --exit-code docs/sbol2-conformance.md` to enforce\n",
    );
    out.push_str("freshness after every change to the SBOL 2 rule catalog.\n\n");
    out.push_str(&format!(
        "Source spec: `{VALIDATION_RULE_SPEC_PATH}` (version {VALIDATION_RULE_SPEC_VERSION}).\n\n"
    ));
    out.push_str(
        "The catalog is the libSBOLj machine ruleset: the 268 numbered SBOL 2 \
         validation rules `sbol-rulegen` emits from `rules.toml`. It is the SBOL 2 \
         peer of the SBOL 3 catalog in [`conformance.md`](conformance.md); both \
         share the `sbol_core` classification types and the same \
         `ValidationConfig`.\n\n",
    );
}

fn render_headline_coverage(out: &mut String, statuses: &[ValidationRuleStatus]) {
    let total = statuses.len();
    let triangle = statuses
        .iter()
        .filter(|s| s.is_machine_uncheckable())
        .count();
    let machine_checkable = total - triangle;
    let implemented = statuses
        .iter()
        .filter(|s| s.is_implemented() && s.is_machine_checkable())
        .count();
    let pct = (implemented as f64 / machine_checkable as f64) * 100.0;
    let unimplemented = machine_checkable - implemented;

    out.push_str("## Headline coverage\n\n");
    out.push_str(&format!(
        "**Every one of the {machine_checkable} machine-checkable rules is backed by a firing \
         negative fixture and a non-firing positive fixture.** Each rule has a hermetic, minimal \
         SBOL 2 document that violates exactly that rule and is asserted to report it at the \
         catalog severity (MUST rules as errors, SHOULD rules as warnings), plus a valid instance \
         of the same construct asserted not to report it, all evaluated under \
         `ValidationConfig::all_on()`. The suite fails at build time if any machine-checkable \
         rule lacks either fixture, so the {machine_checkable}/{machine_checkable} coverage is \
         enforced, not asserted. The per-rule matrix is committed at \
         [`sbol2-negative-coverage.md`](sbol2-negative-coverage.md) and the fixtures live in \
         `crates/sbol2/tests/rule_cases/`; this matches the SBOL 3 validator's standard in \
         [`negative-coverage.md`](negative-coverage.md).\n\n"
    ));
    out.push_str(&format!(
        "All {implemented} of the {machine_checkable} machine-checkable rules carry validation \
         logic. None are marked `Unimplemented` ({pct:.1}%). The empirical SBOLTestSuite \
         negative corpus is reported separately under \
         [InvalidFiles](#invalidfiles-per-rule-negative-corpus) below; its `Deferred` rows \
         record downloaded corpus fixtures not yet strictly error-rejected (SHOULD-level \
         warnings, reader-scope cases, and the \u{25B2} rules that require cross-document \
         resolution), each of which nonetheless has a firing hermetic negative in the per-rule \
         corpus above.\n\n"
    ));
    out.push_str(&format!(
        "The catalog tracks all {total} SBOL 2.3.0 validation rules. {triangle} carry the \
         \u{25B2} status: conditions the spec does not expect a tool to machine-report \
         (they depend on ontology membership, external resolution, or human judgement). \
         Those are tracked separately from the headline percentage: the runtime signals \
         them as `RuleCoverage::not_applied {{ MachineUncheckable }}`, and the validator \
         emits at most warnings (never errors) when its local subset can decide a \
         sub-case.\n\n",
    ));
    out.push_str(&format!(
        "| | Count |\n| --- | --- |\n\
         | Total rules in catalog | {total} |\n\
         | \u{25B2} machine-uncheckable | {triangle} |\n\
         | Machine-checkable | {machine_checkable} |\n\
         |   \u{2192} with validation logic | **{implemented}** |\n\
         |   \u{2192} marked Unimplemented | **{unimplemented}** |\n\n"
    ));
}

fn render_status_taxonomy(out: &mut String, statuses: &[ValidationRuleStatus]) {
    out.push_str("## Status taxonomy\n\n");
    out.push_str(
        "Every rule classifies into one of five statuses shared with the SBOL 3 catalog. \
         The `Blocker` column carries the secondary axis where it applies.\n\n",
    );
    out.push_str("| Status | Count | Algorithm | Diagnostics | Blocker meaning |\n");
    out.push_str("| --- | --- | --- | --- | --- |\n");
    for (status, algorithm, diagnostics, blocker_meaning) in [
        (RuleStatus::Error, "Complete", "Errors", "(none)"),
        (RuleStatus::Warning, "Complete", "Warnings", "(none)"),
        (
            RuleStatus::Configurable,
            "Complete; scope or severity varies by config",
            "Errors / Warnings per config",
            "Which configuration axis: Resolver, Ontology snapshot, Policy, or External",
        ),
        (
            RuleStatus::MachineUncheckable,
            "May have local subset",
            "Warnings only, on positively-decidable cases",
            "Why the rule is \u{25B2}: Ontology, Policy, or External",
        ),
        (
            RuleStatus::Unimplemented,
            "None",
            "Never emits",
            "What's needed: Ontology data, Resolver protocol, Policy decision",
        ),
    ] {
        let count = statuses.iter().filter(|s| s.status == status).count();
        out.push_str(&format!(
            "| {} | {count} | {algorithm} | {diagnostics} | {blocker_meaning} |\n",
            status_label(status),
        ));
    }
    out.push_str(&format!("| **Total** | **{}** | | | |\n\n", statuses.len()));

    let must = statuses
        .iter()
        .filter(|s| s.normative_severity == NormativeSeverity::Must)
        .count();
    let should = statuses
        .iter()
        .filter(|s| s.normative_severity == NormativeSeverity::Should)
        .count();
    let may = statuses
        .iter()
        .filter(|s| s.normative_severity == NormativeSeverity::May)
        .count();
    out.push_str("### By normative force\n\n");
    out.push_str("| RFC 2119 keyword | Count |\n| --- | --- |\n");
    out.push_str(&format!("| MUST | {must} |\n"));
    out.push_str(&format!("| SHOULD | {should} |\n"));
    if may > 0 {
        out.push_str(&format!("| MAY | {may} |\n"));
    }
    out.push('\n');
}

fn render_gate_model(out: &mut String, statuses: &[ValidationRuleStatus]) {
    out.push_str("## Validation gate model\n\n");
    out.push_str(
        "libSBOLj dispatches rule families from distinct passes controlled by four \
         validation-mode flags. Each rule declares the gate (the pass) that runs it. \
         `Always` rules run in every configuration; the other gates run only when their \
         `ValidationConfig` flag is set.\n\n",
    );
    out.push_str("| Gate | `ValidationConfig` flag | Count | Runs when |\n");
    out.push_str("| --- | --- | ---: | --- |\n");
    for (gate, flag, when) in [
        (
            ValidationGate::Always,
            "(always)",
            "Every validation configuration.",
        ),
        (
            ValidationGate::Compliant,
            "`compliant`",
            "The compliant-URI structural family (default on).",
        ),
        (
            ValidationGate::Complete,
            "`complete`",
            "The document-completeness family: every referenced object present (default on).",
        ),
        (
            ValidationGate::BestPractice,
            "`best_practice`",
            "The SHOULD-level recommendation family (default off).",
        ),
    ] {
        let count = statuses.iter().filter(|s| s.gate == gate).count();
        out.push_str(&format!(
            "| {} | {flag} | {count} | {when} |\n",
            gate_label(gate)
        ));
    }
    out.push('\n');
    out.push_str(
        "`ValidationConfig` is the same type the SBOL 3 validator uses. The SBOL 2 \
         validator reads its `compliant`, `complete`, and `best_practice` flags to select \
         gates, plus `types_in_uri` (compliant-URI type-token expectations) and \
         `keep_going` (collect every issue rather than stopping at the first). \
         `ValidationConfig::all_on()` enables every gate; `ValidationConfig::default()` \
         runs `compliant` + `complete` and leaves `best_practice` off, matching \
         libSBOLj's default.\n\n",
    );
}

fn render_configurable_section(out: &mut String, statuses: &[ValidationRuleStatus]) {
    let entries: Vec<&ValidationRuleStatus> = statuses
        .iter()
        .filter(|s| s.status == RuleStatus::Configurable)
        .collect();
    if entries.is_empty() {
        return;
    }
    out.push_str("## Configurable\n\n");
    out.push_str(&format!(
        "**{} rules.** Behavior depends on configuration. The `Blocker` column names the axis:\n\n\
         - `Resolver`: algorithm needs cross-document resolution for full scope. Without it, \
         coverage records `LocalReferencesOnly`.\n\
         - `Ontology`: algorithm correct for every snapshot-known term; out-of-snapshot terms \
         left undecided by design.\n\
         - `Policy`: algorithm runs at the conservative default; stricter or looser modes alter \
         emit behavior.\n\
         - `External`: local-only mode is the implementation. The spec scope is structurally \
         unreachable without external infrastructure; the validator does what it can locally \
         and documents the boundary.\n\n",
        entries.len()
    ));

    out.push_str("### By configuration axis\n\n");
    out.push_str("| Axis | Count |\n| --- | --- |\n");
    for blocker in [
        Blocker::Resolver,
        Blocker::Ontology,
        Blocker::Policy,
        Blocker::External,
    ] {
        let count = entries
            .iter()
            .filter(|e| e.blocker == Some(blocker))
            .count();
        if count > 0 {
            out.push_str(&format!("| `{}` | {count} |\n", blocker_label(blocker)));
        }
    }
    out.push('\n');

    out.push_str("| Rule | Axis | Note |\n");
    out.push_str("| --- | --- | --- |\n");
    for entry in entries {
        let safe_note = entry.note.replace('|', "\\|");
        let blocker = entry.blocker.map(blocker_label).unwrap_or("(unspecified)");
        out.push_str(&format!(
            "| `{}` | `{blocker}` | {safe_note} |\n",
            entry.rule
        ));
    }
    out.push('\n');
}

fn render_machine_uncheckable_section(out: &mut String, statuses: &[ValidationRuleStatus]) {
    let entries: Vec<&ValidationRuleStatus> = statuses
        .iter()
        .filter(|s| s.is_machine_uncheckable())
        .collect();
    if entries.is_empty() {
        return;
    }
    out.push_str("## \u{25B2} MachineUncheckable\n\n");
    out.push_str(&format!(
        "**{} rules.** Violations are NOT to be machine-reported. The validator runs a \
         local subset for some of these and emits warnings on positively-decidable cases; \
         the broader spec rule is always recorded in \
         `RuleCoverage::not_applied {{ MachineUncheckable }}`.\n\n",
        entries.len()
    ));

    out.push_str("| Rule | Blocker | Note |\n");
    out.push_str("| --- | --- | --- |\n");
    for entry in entries {
        let safe_note = entry.note.replace('|', "\\|");
        let blocker = entry.blocker.map(blocker_label).unwrap_or("(none)");
        out.push_str(&format!(
            "| `{}` | `{blocker}` | {safe_note} |\n",
            entry.rule
        ));
    }
    out.push('\n');
}

fn render_corpus_results(out: &mut String) {
    out.push_str("## SBOLTestSuite corpus results\n\n");
    out.push_str(
        "The validator is exercised against the SBOLTestSuite SBOL 2 corpora \
         (SynBioDex/SBOLTestSuite). The corpus is bootstrapped on demand rather than \
         committed; these outcomes are pinned by the tests named below and re-checked \
         on every run.\n\n",
    );

    out.push_str("### Valid corpora\n\n");
    out.push_str(
        "Every file in each corpus parses with **0 parse failures**, and each corpus \
         isolates one validation axis (`crates/sbol2/tests/conformance.rs`):\n\n",
    );
    out.push_str("| Corpus | Files | Flag behavior |\n");
    out.push_str("| --- | ---: | --- |\n");
    out.push_str("| `SBOL2` | 179 | Valid: pass under both the default config and `all_on`. |\n");
    out.push_str(
        "| `SBOL2_ic` | 71 | Incomplete: pass with `complete` off; the completeness family \
         flags them when `complete` is on. |\n",
    );
    out.push_str(
        "| `SBOL2_nc` | 30 | Non-compliant: pass with `compliant` off; the compliant-URI \
         family flags them when `compliant` is on. |\n",
    );
    out.push_str(
        "| `SBOL2_bp` | 11 | Best-practice: error-free under the default; the \
         ontology-usage family flags them at warning severity when `best_practice` is on. |\n\n",
    );

    out.push_str("### InvalidFiles: per-rule negative corpus\n\n");
    out.push_str(
        "`InvalidFiles/sbol-NNNNN.xml` each violate rule `sbol2-NNNNN`. Under \
         `ValidationConfig::all_on()` the validator must reject every file: either the \
         reader fails to parse it (a structural violation caught at read time) or \
         validation reports an error (`crates/sbol2/tests/invalid_files.rs`):\n\n",
    );
    out.push_str("| Outcome | Count | Meaning |\n");
    out.push_str("| --- | ---: | --- |\n");
    out.push_str("| Strict | 166 | The file's exact expected rule fires. |\n");
    out.push_str("| Loose | 14 | Rejected via a related error rather than the exact rule id. |\n");
    out.push_str("| Parse-rejected | 3 | The RDF/XML reader rejects the file at read time. |\n");
    out.push_str(
        "| Deferred | 48 | Exercised but not error-rejected: the violation needs a resolver or \
         cross-document context, is a \u{25B2} machine-uncheckable condition, is a reader-scope \
         concern, or is a SHOULD-level warning that does not fail the file. Every deferred rule \
         still has a firing hermetic negative in `crates/sbol2/tests/rule_cases/`. Tracked in \
         `crates/sbol2/tests/invalid_files_deferred.in` so the strict set is explicit. |\n\n",
    );
}

fn render_cross_impl(out: &mut String) {
    out.push_str("## Cross-implementation agreement\n\n");
    out.push_str(
        "Parser/serializer output is compared triple-for-triple against libSBOLj 2.4.0 \
         reference RDF/XML over 10 committed fixtures in \
         `tests/fixtures/cross-impl-sbol2/` (`crates/sbol2/tests/cross_impl.rs`). Each \
         fixture parses and serializes to a normalized triple set identical to the \
         libSBOLj reference output. This compares parser/serializer output only; the two \
         libraries' validator outputs have not been systematically compared.\n\n",
    );
}

fn render_per_status_section(
    out: &mut String,
    statuses: &[ValidationRuleStatus],
    status: RuleStatus,
    title: &str,
    description: &str,
) {
    let entries: Vec<&ValidationRuleStatus> =
        statuses.iter().filter(|s| s.status == status).collect();
    if entries.is_empty() {
        return;
    }
    let count = entries.len();
    out.push_str(&format!("## {title}\n\n"));
    out.push_str(&format!(
        "**{count} rule{}.** {description}\n\n",
        plural(count)
    ));
    out.push_str("| Rule | Gate | Note |\n");
    out.push_str("| --- | --- | --- |\n");
    for entry in entries {
        let safe_note = entry.note.replace('|', "\\|");
        out.push_str(&format!(
            "| `{}` | {} | {safe_note} |\n",
            entry.rule,
            gate_label(entry.gate)
        ));
    }
    out.push('\n');
}

fn status_label(status: RuleStatus) -> &'static str {
    match status {
        RuleStatus::Error => "`Error`",
        RuleStatus::Warning => "`Warning`",
        RuleStatus::Configurable => "`Configurable`",
        RuleStatus::MachineUncheckable => "`MachineUncheckable`",
        RuleStatus::Unimplemented => "`Unimplemented`",
        _ => "`?`",
    }
}

fn gate_label(gate: ValidationGate) -> &'static str {
    match gate {
        ValidationGate::Always => "`Always`",
        ValidationGate::Compliant => "`Compliant`",
        ValidationGate::Complete => "`Complete`",
        ValidationGate::BestPractice => "`BestPractice`",
        _ => "`?`",
    }
}

fn blocker_label(blocker: Blocker) -> &'static str {
    match blocker {
        Blocker::Ontology => "Ontology",
        Blocker::Resolver => "Resolver",
        Blocker::StrictDatatype => "StrictDatatype",
        Blocker::Policy => "Policy",
        Blocker::External => "External",
    }
}

fn plural(n: usize) -> &'static str {
    if n == 1 { "" } else { "s" }
}