use crate::validation::{
Blocker, NormativeSeverity, RuleStatus, VALIDATION_RULE_SPEC_PATH,
VALIDATION_RULE_SPEC_VERSION, ValidationGate, ValidationRuleStatus,
};
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" }
}