soothfast-report API reference#

Generated by cargo soothfast docs reference Measurements and verified claims come from the latest baseline; CI gates them.

soothfast_report#

soothfast_report::badges#

badge ^function#

pub fn badge(label: &str, message: &str, color: &str) -> Value

Raw shields.io endpoint JSON: {schemaVersion, label, message, color}.

coverage_badge ^function#

pub fn coverage_badge(label: &str, pct: u32) -> Value

Green ≥ 90, yellow ≥ 70, red below.

gate_badge ^function#

pub fn gate_badge(passed: Option<bool>) -> Value

None means no recorded gate verdict — say so rather than guess green.

svg_from ^function#

pub fn svg_from(value: &Value) -> String

Render endpoint JSON (as produced by the builders above) as a flat SVG badge: dark instrument-panel label segment, evidence-colored message.

soothfast_report::changelog#

ApiSection ^enum#

pub enum ApiSection<'a> { Diff { against: &'a str, text: &'a str }, Initial(&'a [SurfaceEntry]) }

What the API section has to report.

The two cases are separate types rather than an empty-string convention: "nothing changed" and "there was nothing to compare against" read the same in prose but mean opposite things, and a changelog that confuses them reports calm where it had no input at all.

Change ^struct#

pub struct Change { pub kind: String, pub scope: Option<String>, pub breaking: bool, pub subject: String, pub pr: Option<u32> }

One merged change, read off a conventional-commit subject.

DraftInputs ^struct#

pub struct DraftInputs<'a> { pub api: ApiSection<'a>, pub changes: &'a [Change], pub icons: &'a Icons, pub old_baseline: Option<&'a Value>, pub new_baseline: &'a Value, pub thresholds: PerfThresholds }

Inputs already computed by the CLI (API section, two baselines).

Icons ^struct#

pub struct Icons {  }

Section icons, keyed by the lowercased section name a release renders (breaking changes, features, fixes, performance, documentation, dependencies, internal).

A repo overrides any subset through [changelog.icons] in its soothfast.toml; whatever it leaves out keeps the shipped default, so a consumer never has to restate the whole vocabulary to change one glyph.

PerfThresholds ^struct#

pub struct PerfThresholds { pub instructions_pct: f64, pub allocs_pct: f64 }

Per-metric movement a delta table is willing to report, as percentages.

These mirror the gate's own thresholds and are passed in rather than defined here, so the changelog reports exactly what the gate would have flagged instead of drifting from it.

Only deterministic metrics have thresholds, because a changelog is a permanent record: walltime moves 15-20% between two runs of identical code on a shared CI runner, so recording it means rewriting the section on every merge to say nothing. Walltime regressions are gate's job, where a human reads the verdict against a live noise floor.

changes_from_subjects ^function#

pub fn changes_from_subjects(subjects: &[String]) -> Vec<Change>

Parse type(scope)!: subject (#N) subjects. Release commits and the bots that regenerate derived artifacts are dropped, since a release listing its own paperwork is noise.

draft ^function#

pub fn draft(inputs: &DraftInputs) -> String

Render the "Unreleased" draft section: API surface + perf table.

unparsed_subjects ^function#

pub fn unparsed_subjects(subjects: &[String]) -> Vec<&str>

Subjects that are not conventional commits of a known type: the ones a release would otherwise drop in silence.

soothfast_report::llms#

SurfaceEntry ^struct#

pub struct SurfaceEntry { pub path: String, pub kind: String, pub signature: String, pub pkg: String, pub summary: String, pub docs: String }

One public item as fed by the CLI (from the docs-engine surface).

render ^function#

pub fn render(pkg: &str, entries: &[SurfaceEntry], baseline: &Value) -> String

Render llms.txt: every public item grouped by crate, with its full doc comment and measured facts attributed via covers (or direct id) matching.

soothfast_report::perf_table#

Row ^struct#

pub struct Row { pub id: String, pub instructions: Option<u64>, pub median_ns: Option<f64>, pub p99_ns: Option<f64>, pub allocs: Option<u64>, pub polls: Option<u64> }

One measured item's metrics, each None when that backend didn't run.

html ^function#

pub fn html(baseline: &Value) -> String

rows rendered as a plain <table> for embedding in the docs site.

markdown ^function#

pub fn markdown(baseline: &Value) -> String

rows rendered as a GitHub-flavored markdown table.

rows ^function#

pub fn rows(baseline: &Value) -> Vec<Row>

One Row per measured item in the baseline, in baseline (map) order.

soothfast_report::trend_chart#

METRICS ^constant#

pub const METRICS: &[(&[&str

(metric key path in baseline items, display name, mover threshold in percent drift, fleet_relative). Walltime is fleet-relative: runner-speed shifts move every item together, so each series divides out the fleet median before anything is called a mover. Counter metrics are deterministic and compare directly against their first point.

render ^function#

pub fn render( points: &[Value], key: &[&str; 2], title: &str, threshold_pct: f64, fleet_relative: bool, ) -> Option<String>

Render one metric's chart; None when fewer than 2 points exist.