HTTP API: quality

What this executable's own public surface is held to, measured from its syntax tree: documentation that says more than the signature, an executable example on everything that carries behaviour, a module boundary something exercises, and every command of the command line accounted for against the capability registry. The rules are project.rust-public-api-quality and project.operation-transport-parity; this is the measurement of them.

Rendered from docs/generated/openapi.json, which the executable generates from its capability registry and CI refuses stale. The raw document is at /openapi.json; a running server serves the same document at its own /openapi.json and Swagger UI at /swagger.

quality

GET /api/v1/quality quality.report

Public API quality report

The crate's exported surface measured against the repository's rules: how many items are documented and exampled, how many modules are documented, exampled and behaviourally tested, how the canonical operations stand against the command line, HTTP, OpenAPI and MCP, and one finding per violation carrying a stable code, the rule that requires it, its file and line, why it matters and what to do about it.

query
behaviorally_verified
benchmark required
cache process (max_entries=8, ttl_seconds=10)
MCP tool majordomus_quality
MCP resource {"name": "quality", "uri": "majordomus://quality"}
$ quality report

Query parameters

name	type	required	description	examples
code	string	no	Only findings carrying this code (`RUST_PUBLIC_MISSING_EXAMPLE`). All of them when absent. A code nothing recognises is refused rather than answered with an empty list, so a typo cannot read as a clean report.
path	string	no	Only findings whose file path starts with this, repository-relative (`apps/majordomus-cli/src/web`). All of them when absent.
summary_only	boolean	no	Answer with the counts and leave the findings out. For a caller that wants the state of the crate and not the list of what to do about it.	default: false
include_baselined	boolean	no	Include the findings the ratchet already accepts, which are left out by default. The default is what a gate wants: only what is new. This is what a person paying the debt down wants, and it is what `--write-baseline` must ask for — a baseline written from a report that had the baseline applied to it would empty the file, accepting nothing and failing on everything the next time it ran.	default: false

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/quality?summary_only=false&include_baselined=false"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	QualityAnswer	Public API quality report: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

GET /api/v1/quality/rustdoc quality.rustdoc

Rustdoc tree integrity

The crate's rustdoc tree — the rustdoc surface's artifact, as the web topology resolves it — judged against the crate's own inventory of exported items: every item that owns a page has it at the route rustdoc gives it, no item page is left without an item, the tree declares it was built from HEAD, the library's index is present and names the crate, its assets are present, every relative link resolves, and no file names the machine it was built on or carries a credential. Answers the verdict (clean, findings, or no_tree when there is nothing to judge), the counts it joined, every exported module with its page, and one typed finding per defect with the file and what to do.

query
behaviorally_verified
benchmark required
cache process (max_entries=8, ttl_seconds=10)
MCP tool majordomus_quality_rustdoc
MCP resource {"name": "quality-rustdoc", "uri": "majordomus://quality/rustdoc"}
$ quality rustdoc

Query parameters

name	type	required	description	examples
kind	RustdocFindingKind \| null	no	Only findings of this kind (`missing-page`, `link`, `stale`). All of them when absent. The verdict and the counts are never narrowed: a filter that changed the verdict would be a way of passing a tree with a missing page.	missing-pages-summary: "missing-page"
summary_only	boolean	no	Answer with the verdict, the counts and the module routes, and leave the findings out.	default: falsemissing-pages-summary: true

Try it

The port is whatever the server logged; 8741 is the one it asks for first. The values are the operation's first example.

curl -s "http://127.0.0.1:8741/api/v1/quality/rustdoc?kind=missing-page&summary_only=false"

Tested by apps/majordomus-cli/tests/http_serve.rs, which replays the route with these values against a server on a real socket.

Responses

status	body	meaning
200	RustdocReport	Rustdoc tree integrity: the result.
400	ErrorBody	`invalid_input`: The input does not fit the schema: a parameter of the wrong type, an unknown one, or a value the capability rejects.
404	ErrorBody	`not_found`: The input names something the repository does not hold.
500	ErrorBody	`internal`: The capability failed for a reason of its own; the message names it.
default	ErrorBody	Any other failure the transport reports: 405 `method_not_allowed` for another method on this path, 400 `invalid_input` for a body that is not a JSON object.

Schemas

The components only this tag's operations use. Each row is the type's own field, its doc comment the description; a type another page owns links there.

Exemption

object

A group of items the example policy does not apply to, with the reason it does not.

property	type	required	description
reason	string	yes	The reason, as the policy names it.
items	integer (uint)	yes	How many items it covers.

Used by PublicApiQuality

ModuleQuality

object

What the exported module surface looks like.

property	type	required	description
modules	integer (uint)	yes	Modules the crate exports, the crate root included.
documented	integer (uint)	yes	Of those, how many carry a `//!` header.
exampled	integer (uint)	yes	How many carry an executable example in that header.
behaviourally_tested	integer (uint)	yes	How many something exercises: an in-file test, or a test that names them.

Used by QualityReport

OperationParity

object

What the canonical operations look like against the transports that project them.

property	type	required	description
canonical	integer (uint)	yes	Executable capabilities in the registry.
cli	integer (uint)	yes	Of those, how many declare a command-line projection.
http	integer (uint)	yes	How many declare an HTTP route.
openapi	integer (uint)	yes	How many the OpenAPI document describes.
mcp	integer (uint)	yes	How many declare an MCP tool.
cli_commands	integer (uint)	yes	Commands of the command line, leaves and runnable parents.
cli_from_capability	integer (uint)	yes	Of those, how many are the projection of a capability.
cli_local	integer (uint)	yes	How many are declared to belong to the command line alone, with a reason.

Used by QualityReport

PublicApiQuality

object

What the exported item surface looks like.

property	type	required	description
items	integer (uint)	yes	Items the crate exports, of every kind.
documented	integer (uint)	yes	Of those, how many carry documentation.
owe_example	integer (uint)	yes	How many owe an executable example under the policy.
exampled	integer (uint)	yes	Of those, how many have one that counts.
exempt	array of Exemption → Exemption	yes	How many are exempt from the example policy for a structural reason, and why, by reason, so that the exemptions are visible rather than implied by a subtraction.

Used by QualityReport

QualityAnswer

object

The answer: the measurement, or the reason there was not one.

property	type	required	description
measured	boolean	yes	Whether a crate was found and measured. `false` is a complete answer, not a failure: the layer installs into repositories that carry no Rust crate, and a doctrine that cannot apply is not a violation.
reason	string \| null	no	Why nothing was measured, when nothing was.
report	QualityReport → QualityReport	yes	The measurement. Present and empty-of-findings when `measured` is false, so that a consumer reads one shape either way and `measured` is the only question it must ask.
passes	boolean	yes	Whether the report as filtered leaves nothing blocking. Answered here so that a caller over any transport reads the verdict rather than deriving it, and so that the command line's exit code and this field can never disagree.
baselined	integer (uint)	yes	The findings the ratchet accepts because they stood when the rule landed. A finding outside this count is what fails the gate.

Used by quality.report

QualityReport

object

One measurement of one crate, and everything found wrong in it.

property	type	required	description
schema	string	no	`SCHEMA`.
target	string	yes	What was measured: the crate directory, repository-relative.
public_api	PublicApiQuality → PublicApiQuality	yes	The exported item surface.
modules	ModuleQuality → ModuleQuality	yes	The exported module surface.
operations	OperationParity → OperationParity	yes	The canonical operations against their transports.
violations	array of Violation → Violation	yes	Every finding, errors first, then by file and line.

Used by QualityAnswer

QualitySeverity

"error" | "warning"

How much a finding matters.

There are two levels and not five, because the only question a gate can answer is whether the change may land. A warning is a finding the repository has decided not to block on; nothing else is a warning.

errorThe gate fails.
warningReported, and the gate passes.

Used by Violation

RustdocAcceptedLinks

object

The unresolved references of one RustdocLinkClass: how many, on how many pages, and every distinct one as the pages write it. Every class is listed, with zeros when the tree has none, so that "none" is an answer and not an omission.

property	type	required	description
class	RustdocLinkClass → RustdocLinkClass	yes	The class.
links	integer (uint)	yes	References of the class, across every page.
pages	integer (uint)	yes	Pages carrying at least one.
written	array of string	yes	Every distinct reference as written, fragment included, in canonical order.

Used by RustdocCounts

RustdocCounts

object

What the check counted, so a reader can see what was joined and not only what failed.

property	type	required	description
exported_items	integer (uint)	yes	Items the library exports, of every kind.
page_owning_items	integer (uint)	yes	Of every documented target, the items that own a page: modules, types, traits, free functions, constants, statics, aliases, macros.
derived_pages	integer (uint)	yes	Pages those items derive; more than the items when a re-export documents one twice.
item_pages	integer (uint)	yes	Item pages found in the tree: every page under a crate directory that is neither a redirect stub nor a system file.
redirect_stubs	integer (uint)	yes	Pages that only redirect to where an item is documented.
system_files	integer (uint)	yes	rustdoc's own files: static assets, the search index, source pages, implementor lists, the settings and help pages, every crate's all-items page and sidebar.
html_files	integer (uint)	yes	Every HTML file of the tree, whatever it is.
files	integer (uint)	yes	Every file of the tree.
relative_links	integer (uint)	yes	Relative links followed, across every page: resolved, broken and accepted alike.
accepted_links	array of RustdocAcceptedLinks → RustdocAcceptedLinks	yes	The unresolved references that are rustdoc's own, by class; every class is listed.
external_links	array of RustdocHostLinks → RustdocHostLinks	yes	External links, by host.

Used by RustdocReport

RustdocFinding

object

One finding about the tree.

property	type	required	description
kind	RustdocFindingKind → RustdocFindingKind	yes	What is wrong.
file	string	yes	The file of the tree it is about, tree-relative; empty when it is about the tree as a whole.
subject	string	yes	What exactly: the item path of a missing page, the target of a broken link, the pattern that matched.
message	string	yes	One sentence, specific to this occurrence.
remedy	string	yes	What to do, from the kind.

Used by RustdocReport

RustdocFindingKind

What is wrong with the tree, as a stable code.

missing-pageAn exported item that owns a page has no page at its derived route.
orphan-pageAn item page no item of the crate derives: a leftover, or a route rule this check has wrong.
staleThe tree declares it was built from a revision other than the repository's HEAD.
undeclaredThe tree carries no declaration of what it is or what it was built from.
crate-indexThe library's index page is absent, or does not say it is the library's.
assetA stylesheet, script, font or search file the library's index page needs is absent.
linkA relative link of a page resolves to no file of the tree.
machine-pathA file names a path of the machine it was built on.
secretA file carries the shape of a credential.

Used by quality.rustdoc RustdocFinding

RustdocHostLinks

object

How many external links the tree carries to one host. Counted, never fetched: a check that went to the network would be a check whose verdict depended on it.

property	type	required	description
host	string	yes	The host: `doc.rust-lang.org`.
links	integer (uint)	yes	How many links point at it, across every page.

Used by RustdocCounts

RustdocLinkClass

"inherited-documentation" | "unwritten-implementors"

A kind of unresolved reference that is rustdoc's and not the crate's: decided by where it sits on its page, counted, and never a finding.

inherited-documentationA relative link inside a docblock that rustdoc copied from another crate: the documentation of an implementation listed under Auto Trait Implementations or Blanket Implementations of a trait no page of this tree documents (the impl's header links no trait page of the tree). The text is the other crate's, written relative to that crate's own pages — tracing's dispatcher#setting-the-default-subscriber — so it resolves nowhere under this tree and nothing in this crate can change it. The same link anywhere else, or under an implementation of a trait of this crate, is a link finding.
unwritten-implementorsThe implementors script a trait's page loads — trait.impl/<crate>/<path>/trait.<Name>.js, for the trait the page documents — when rustdoc wrote none. rustdoc references it from every trait page and writes it only when it has implementors to list from the documented crates; the page renders its own crate's implementors inline and is complete without it. Any other absent script is a link finding.

Used by RustdocAcceptedLinks

RustdocModuleRoute

object

One exported module and the page rustdoc documents it on: the mapping a consumer that links into the tree reads, rather than deriving a route of its own.

property	type	required	description
path	string	yes	The module's crate path: `majordomus_cli::quality`.
route	string	yes	Its page, relative to the tree root: `majordomus_cli/quality/index.html`.

Used by RustdocReport

RustdocReport

object

One judgement of one rustdoc tree against the crate it documents.

property	type	required	description
schema	string	yes	`SCHEMA`.
tree	string	yes	The tree judged, repository-relative when it is inside the repository.
mount	string \| null	no	The mount the tree is published at, from the web topology.
crate	string	yes	The library's crate name: the directory of the tree it is documented in. Empty when the repository has no crate.
built_from	string \| null	no	The revision the tree declares it was built from.
head	string \| null	no	The repository's HEAD when it was judged.
verdict	RustdocVerdict → RustdocVerdict	yes	The verdict.
reason	string \| null	no	Why nothing was judged, when nothing was.
counts	RustdocCounts → RustdocCounts	yes	What was counted.
modules	array of RustdocModuleRoute → RustdocModuleRoute	yes	Every exported module of the library with its page, in canonical order: the one module-to-route mapping every consumer reads. Derived from the crate, so it is answered even when the tree is absent.
findings	array of RustdocFinding → RustdocFinding	yes	Every finding, in canonical order.

Used by quality.rustdoc

RustdocVerdict

"clean" | "findings" | "no_tree"

What the tree was judged to be.

cleanThe tree holds every page the crate derives and nothing wrong was found.
findingsAt least one finding stands.
no_treeNothing could be judged: the tree, or the crate that documents it, is absent. Never a pass — the producer has not run, and a check that cannot see its subject says so.

Used by RustdocReport

Violation

object

One finding: what, where, why, and what to do.

property	type	required	description
code	ViolationCode → ViolationCode	yes	The stable code.
severity	QualitySeverity → QualitySeverity	yes	How bad it is.
rule	string	yes	The canonical id of the rule that requires this.
path	string	yes	Where it is, repository-relative; empty when the finding is not about a file.
line	integer \| null	no	The line, 1-based; `None` when the finding is not about a line.
symbol	string	yes	The item's full path, or the command, or the capability id: what the finding is about.
message	string	yes	One sentence, specific to this occurrence.
why	string	yes	Why it matters, from the code.
remediation	string	yes	What to do, from the code.

Used by QualityReport

ViolationCode

What is wrong, as a stable machine-readable code.

The codes are the contract between the validator and everything downstream: CI annotations, Cockpit filters, documentation anchors and an agent deciding what to fix. A code is never renamed once it has shipped; a rule that stops existing takes its code with it.

RUST_PUBLIC_MISSING_DOCSAn exported item carries no documentation at all.
RUST_PUBLIC_THIN_DOCSAn exported item's documentation says nothing its signature had not already said.
RUST_PUBLIC_MISSING_EXAMPLEAn exported item that carries behaviour has no executable example.
RUST_EXAMPLE_NOT_EXECUTABLEEvery example an item has is ignored or is prose in a fenced box.
RUST_EXAMPLE_PLACEHOLDERAn example asserts nothing, or asserts something that is true of any program.
RUST_EXAMPLE_DOES_NOT_NAME_SUBJECTAn example never names the item it is documenting.
RUST_MODULE_MISSING_DOCSAn exported module carries no module-level documentation.
RUST_MODULE_MISSING_EXAMPLEAn exported module has no module-level executable example.
RUST_MODULE_MISSING_BEHAVIOURAL_TESTNo test names an exported module, and it declares none of its own.
OPERATION_CLI_UNCLASSIFIEDA command of the command line is neither a canonical capability nor classified as belonging to the command line alone.
OPERATION_CLASSIFICATION_STALEA command is classified as belonging to the command line alone, and the command line no longer has it.
OPERATION_CLASSIFICATION_CONFLICTA command is classified as local and bound to a capability: two answers to one question.
OPERATION_MISSING_OPENAPIA capability declares an HTTP route and the OpenAPI document does not describe it.
OPERATION_PROJECTION_MISSINGA capability declares a projection that the projection itself does not carry.
OPERATION_PROJECTION_ORPHANA projection carries an entry the registry does not hold.

Used by Violation