HTTP API: quality

Čemu musí vyhovovat veřejný povrch tohoto spustitelného souboru, měřeno z jeho syntaktického stromu: dokumentace, která říká víc než signatura, spustitelný příklad u všeho, co nese chování, hranice modulu, kterou něco procvičuje, a každý příkaz příkazové řádky zúčtovaný proti registru schopností. Pravidla jsou project.rust-public-api-quality a project.operation-transport-parity; toto je jejich měření.

Vykresleno z docs/generated/openapi.json, který spustitelný soubor generuje ze svého registru schopností a CI jej odmítne, je-li zastaralý. Surový dokument je na /openapi.json; běžící server servíruje stejný dokument na vlastní /openapi.json a Swagger UI na /swagger.

quality

GET /api/v1/quality quality.report

Zpráva o kvalitě veřejného API

Exportovaný povrch crate změřený proti pravidlům repozitáře: kolik položek je zdokumentovaných a má příklad, kolik modulů je zdokumentovaných, má příklad a je behaviorálně otestováno, jak stojí kanonické operace vůči příkazové řádce, HTTP, OpenAPI a MCP a jedno zjištění na porušení nesoucí stabilní kód, pravidlo, které ho vyžaduje, soubor a řádek, proč na něm záleží a co s tím dělat.

query
behaviorally_verified
vyžaduje se měření výkonu
cache procesu (max_entries=8, ttl_seconds=10)
nástroj MCP majordomus_quality
zdroj MCP {"name": "quality", "uri": "majordomus://quality"}
$ quality report

Parametry dotazu

název	typ	povinné	popis	příklady
kód	string	ne	Jen nálezy nesoucí tento kód (`RUST_PUBLIC_MISSING_EXAMPLE`). Bez hodnoty všechny. Kód, který nic nezná, se odmítne, ne zodpoví prázdným seznamem, aby překlep nemohl vypadat jako čistý report.
path	string	ne	Jen nálezy, jejichž cesta k souboru s tímto začíná, relativně k repozitáři (`apps/majordomus-cli/src/web`). Všechny, když chybí.
summary_only	boolean	ne	Odpovědět s počty a nálezy vynechat. Pro volajícího, který chce stav crate, a ne seznam toho, co s tím dělat.	výchozí: false
include_baselined	boolean	ne	Zahrnout zjištění, která ratchet už přijímá a která se ve výchozím stavu vynechávají. Výchozí stav je to, co chce kontrola: jen to, co je nové. Toto je to, co chce člověk splácející dluh, a to, o co musí žádat `--write-baseline` — základ zapsaný ze zprávy, na kterou byl základ aplikován, by soubor vyprázdnil, nepřijal by nic a při příštím běhu by selhal na všem.	výchozí: false

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

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

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	QualityAnswer	Zpráva o kvalitě veřejného API: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

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

Integrita stromu rustdoc

Strom rustdoc crate — artefakt povrchu rustdoc, jak ho řeší webová topologie — posuzovaný proti vlastnímu inventáři exportovaných položek crate: každá položka, která vlastní stránku, ji má na trase, kterou jí rustdoc dává, žádná stránka položky nezůstala bez položky, strom deklaruje, že byl sestaven z HEAD, index knihovny je přítomen a jmenuje crate, jeho assety jsou přítomny, každý relativní odkaz se vyřeší a žádný soubor nejmenuje stroj, na kterém byl sestaven, ani nenese přihlašovací údaj. Odpovídá verdiktem (clean, findings, nebo no_tree, když není co posuzovat), počty, které spojil, každým exportovaným modulem s jeho stránkou a jedním typovaným zjištěním na vadu se souborem a tím, co dělat.

query
behaviorally_verified
vyžaduje se měření výkonu
cache procesu (max_entries=8, ttl_seconds=10)
nástroj MCP majordomus_quality_rustdoc
Zdroj MCP {"name": "quality-rustdoc", "uri": "majordomus://quality/rustdoc"}
$ quality rustdoc

Parametry dotazu

název	typ	povinné	popis	příklady
druh	RustdocFindingKind \| null	ne	Pouze zjištění tohoto druhu (`missing-page`, `link`, `stale`). Bez zadání všechna. Verdikt a počty se nikdy nezužují: filtr, který by změnil verdikt, by byl způsob, jak projít stromem s chybějící stránkou.	missing-pages-summary: "missing-page"
summary_only	boolean	ne	Odpovězte verdiktem, počty a trasami modulů a nálezy vynechte.	výchozí: falsemissing-pages-summary: true

Vyzkoušejte

Port je ten, který server zalogoval; 8741 je ten, o který žádá jako první. Hodnoty jsou první příklad operace.

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

Testováno v apps/majordomus-cli/tests/http_serve.rs, který přehrává routu s těmito hodnotami proti serveru na skutečném socketu.

Odpovědi

status	tělo	význam
200	RustdocReport	Integrita stromu rustdoc: výsledek.
400	ErrorBody	`invalid_input`: Vstup neodpovídá schématu: parametr špatného typu, neznámý parametr nebo hodnota, kterou schopnost odmítne.
404	ErrorBody	`not_found`: Vstup pojmenovává něco, co repozitář nemá.
500	ErrorBody	`internal`: Schopnost selhala z vlastního důvodu; zpráva ho pojmenovává.
výchozí	ErrorBody	Jakékoli jiné selhání, které transport hlásí: 405 `method_not_allowed` pro jinou metodu na této cestě, 400 `invalid_input` pro tělo, které není objektem JSON.

Schémata

Komponenty, které používají jen operace tohoto tagu. Každý řádek je pole daného typu, jeho doc komentář je popis; typ vlastněný jinou stránkou na ni odkazuje.

Výjimka

object

Skupina položek, na které se politika příkladů nevztahuje, s důvodem, proč ne.

vlastnost	typ	povinné	popis
důvod	string	ano	Důvod tak, jak jej jmenuje politika.
položky	integer (uint)	ano	Kolik položek pokrývá.

Používá PublicApiQuality

ModuleQuality

object

Jak vypadá exportovaný povrch modulu.

vlastnost	typ	povinné	popis
moduly	integer (uint)	ano	Moduly, které crate exportuje, včetně kořene crate.
zdokumentováno	integer (uint)	ano	Z nich kolik nese hlavičku `//!`.
s příkladem	integer (uint)	ano	Kolik z nich nese spustitelný příklad v této hlavičce.
behaviourally_tested	integer (uint)	ano	Kolik čeho se něco týká: test uvnitř souboru, nebo test, který je jmenuje.

Používá QualityReport

OperationParity

object

Jak vypadají kanonické operace proti transportům, které je promítají.

vlastnost	typ	povinné	popis
kanonické	integer (uint)	ano	Spustitelné schopnosti v registru.
cli	integer (uint)	ano	Z nich kolik deklaruje projekci příkazového řádku.
http	integer (uint)	ano	Kolik jich deklaruje trasu HTTP.
openapi	integer (uint)	ano	Kolik jich dokument OpenAPI popisuje.
mcp	integer (uint)	ano	Kolik jich deklaruje nástroj MCP.
cli_commands	integer (uint)	ano	Příkazy příkazové řádky, koncové i spustitelné nadřazené.
cli_from_capability	integer (uint)	ano	Z nich kolik je projekcí schopnosti.
cli_local	integer (uint)	ano	Kolik jich je deklarováno jako patřících jen příkazové řádce, s důvodem.

Používá QualityReport

PublicApiQuality

object

Jak vypadá exportovaný povrch položek.

vlastnost	typ	povinné	popis
položky	integer (uint)	ano	Položky, které crate exportuje, všech druhů.
zdokumentováno	integer (uint)	ano	Z nich kolik nese dokumentaci.
owe_example	integer (uint)	ano	Kolik jich podle politiky dluží spustitelný příklad.
s příkladem	integer (uint)	ano	Z nich kolik jich má takový, který se počítá.
exempt	pole Exemption → Exemption	ano	Kolik jich je vyňato z příkladové politiky ze strukturního důvodu a proč, podle důvodu, aby výjimky byly vidět, a ne naznačené odečtem.

Používá QualityReport

QualityAnswer

object

Odpověď: měření, nebo důvod, proč žádné nebylo.

vlastnost	typ	povinné	popis
naměřeno	boolean	ano	Zda byl nalezen a změřen crate. `false` je úplná odpověď, ne selhání: vrstva se instaluje do repozitářů, které žádný crate Rustu nenesou, a doktrína, která se nemůže použít, není porušení.
důvod	string \| null	ne	Proč se nic neměřilo, když se nic neměřilo.
report	QualityReport → QualityReport	ano	Měření. Přítomné a bez nálezů, když je `measured` false, takže spotřebitel čte v obou případech jeden tvar a `measured` je jediná otázka, kterou musí položit.
průchody	boolean	ano	Zda zpráva po filtrování nic neblokuje. Odpovídá se tu, aby volající přes jakýkoli transport četl verdikt, ne ho odvozoval, a aby výstupní kód příkazové řádky a toto pole nemohly nikdy být v rozporu.
zapsáno do baseline	integer (uint)	ano	Nálezy, které ratchet přijímá, protože existovaly, když pravidlo přistálo. Nález mimo tento počet je to, co kontrolu shazuje.

Používá quality.report

QualityReport

object

Jedno měření jednoho crate a vše, co se v něm ukázalo jako špatné.

vlastnost	typ	povinné	popis
schema	string	ne	`SCHEMA`.
cíl	string	ano	Co bylo měřeno: adresář crate, relativně k repozitáři.
public_api	PublicApiQuality → PublicApiQuality	ano	Exportovaná plocha položek.
moduly	ModuleQuality → ModuleQuality	ano	Exportovaný povrch modulu.
operace	OperationParity → OperationParity	ano	Kanonické operace proti jejich transportům.
porušení	pole Violation → Violation	ano	Každé zjištění, nejdřív chyby, pak podle souboru a řádku.

Používá QualityAnswer

QualitySeverity

"error" | "warning"

Jak moc nález záleží.

Jsou dvě úrovně, a ne pět, protože jediná otázka, na kterou kontrola umí odpovědět, je, zda smí změna přistát. Varování je nález, na kterém se repozitář rozhodl neblokovat; nic jiného varování není.

errorKontrola selže.
warningNahlášeno a kontrola projde.

Používá Violation

RustdocAcceptedLinks

object

Nerozřešené odkazy jedné RustdocLinkClass: kolik, na kolika stránkách a každý odlišný tak, jak ho stránky zapisují. Vypsána je každá třída, s nulami, když ji strom nemá, aby „žádné“ byla odpověď a ne opomenutí.

vlastnost	typ	povinné	popis
třída	RustdocLinkClass → RustdocLinkClass	ano	Třída.
odkazy	integer (uint)	ano	Reference třídy napříč každou stránkou.
stránky	integer (uint)	ano	Stránky, které nesou alespoň jednu.
zapsáno	array of string	ano	Každý odlišný odkaz tak, jak je napsán, včetně fragmentu, v kanonickém pořadí.

Používá RustdocCounts

RustdocCounts

object

Co kontrola počítala, aby čtenář viděl, co bylo spojeno, a ne jen co selhalo.

vlastnost	typ	povinné	popis
exported_items	integer (uint)	ano	Položky, které knihovna exportuje, všech druhů.
page_owning_items	integer (uint)	ano	Ze všech zdokumentovaných cílů položky, které vlastní stránku: moduly, typy, traity, volné funkce, konstanty, statiky, aliasy, makra.
derived_pages	integer (uint)	ano	Stránky, které tyto položky odvozují; více než položek, když re-export dokumentuje jednu dvakrát.
item_pages	integer (uint)	ano	Nalezené stránky položek ve stromu: každá stránka pod adresářem cratu, která není ani zástupným přesměrováním, ani systémovým souborem.
redirect_stubs	integer (uint)	ano	Stránky, které jen přesměrovávají tam, kde je položka zdokumentována.
system_files	integer (uint)	ano	vlastní soubory rustdocu: statické assety, vyhledávací index, stránky zdrojů, seznamy implementorů, stránky nastavení a nápovědy, stránka všech položek každého crate a postranní panel.
html_files	integer (uint)	ano	Každý soubor HTML ve stromu, ať je jakýkoli.
soubory	integer (uint)	ano	Každý soubor stromu.
relative_links	integer (uint)	ano	Následované relativní odkazy napříč všemi stránkami: vyřešené, rozbité i přijaté.
accepted_links	pole RustdocAcceptedLinks → RustdocAcceptedLinks	ano	Nerozřešené odkazy, které patří rustdocu, podle třídy; vypsána je každá třída.
external_links	pole RustdocHostLinks → RustdocHostLinks	ano	Externí odkazy podle hostitele.

Používá RustdocReport

RustdocFinding

object

Jedno zjištění o stromu.

vlastnost	typ	povinné	popis
druh	RustdocFindingKind → RustdocFindingKind	ano	Co je špatně.
soubor	string	ano	Soubor stromu, kterého se to týká, relativní ke stromu; prázdné, když se to týká stromu jako celku.
předmět	string	ano	Co přesně: cesta položky chybějící stránky, cíl rozbitého odkazu, vzor, který odpovídal.
zpráva	string	ano	Jedna věta, specifická pro tento výskyt.
náprava	string	ano	Co dělat, podle druhu.

Používá RustdocReport

RustdocFindingKind

Co je se stromem špatně, jako stabilní kód.

missing-pageExportovaná položka, která vlastní stránku, nemá stránku na své odvozené trase.
orphan-pageStránka položky, kterou žádná položka crate neodvozuje: pozůstatek, nebo pravidlo trasy, které tato kontrola má špatně.
staleStrom deklaruje, že byl sestaven z jiné revize, než je HEAD repozitáře.
undeclaredStrom nenese žádnou deklaraci toho, čím je nebo z čeho byl sestaven.
crate-indexIndexová stránka knihovny chybí, nebo neříká, že je knihovny.
assetStylesheet, skript, písmo nebo vyhledávací soubor, který potřebuje indexová stránka knihovny, chybí.
linkRelativní odkaz stránky nevede na žádný soubor stromu.
machine-pathSoubor jmenuje cestu stroje, na kterém byl sestaven.
secretSoubor nese tvar přihlašovacího údaje.

Používá quality.rustdoc RustdocFinding

RustdocHostLinks

object

Kolik externích odkazů strom nese na jednoho hostitele. Počítá se, nikdy se nestahuje: kontrola, která by šla do sítě, by byla kontrolou, jejíž verdikt na ní závisí.

vlastnost	typ	povinné	popis
host	string	ano	Hostitel: `doc.rust-lang.org`.
odkazy	integer (uint)	ano	Kolik odkazů na něj míří napříč všemi stránkami.

Používá RustdocCounts

RustdocLinkClass

"inherited-documentation" | "unwritten-implementors"

Druh nerozřešeného odkazu, který patří rustdocu a ne crate: rozhoduje se podle toho, kde na stránce sedí, počítá se a nikdy není zjištěním.

inherited-documentationRelativní odkaz uvnitř docblocku, který rustdoc zkopíroval z jiného crate: dokumentace implementace uvedené pod Auto Trait Implementations nebo Blanket Implementations traitu, který žádná stránka tohoto stromu nedokumentuje (hlavička impl nelinkuje žádnou stránku traitu stromu). Text je z jiného crate, psaný relativně k vlastním stránkám toho crate — dispatcher#setting-the-default-subscriber z tracingu — takže se nikde pod tímto stromem nevyřeší a nic v tomto crate to nemůže změnit. Tentýž odkaz kdekoli jinde nebo pod implementací traitu tohoto crate je nález link.
unwritten-implementorsSkript implementorů, který stránka traitu načítá — trait.impl/<crate>/<path>/trait.<Name>.js, pro trait, který stránka dokumentuje — když rustdoc žádný nezapsal. rustdoc na něj odkazuje z každé stránky traitu a zapisuje ho, jen když má z dokumentovaných crates co vypsat jako implementory; stránka vykresluje implementory svého crate přímo a je bez něj úplná. Jakýkoli jiný chybějící skript je nález link.

Používá RustdocAcceptedLinks

RustdocModuleRoute

object

Jeden exportovaný modul a stránka, na které ho rustdoc dokumentuje: mapování, které čte konzument odkazující do stromu, místo aby si odvozoval vlastní trasu.

vlastnost	typ	povinné	popis
path	string	ano	Cesta modulu v crate: `majordomus_cli::quality`.
route	string	ano	Jeho stránka, relativně ke kořeni stromu: `majordomus_cli/quality/index.html`.

Používá RustdocReport

RustdocReport

object

Jedno posouzení jednoho stromu rustdoc vůči crate, který dokumentuje.

vlastnost	typ	povinné	popis
schema	string	ano	`SCHEMA`.
strom	string	ano	Posuzovaný strom, relativně k repozitáři, pokud je uvnitř repozitáře.
mount	string \| null	ne	Mount, na kterém je strom publikován, z topologie webu.
crate	string	ano	Název crate knihovny: adresář stromu, v němž je zdokumentována. Prázdné, když repozitář nemá žádný crate.
built_from	string \| null	ne	Revize, ze které strom deklaruje, že byl vybuildován.
head	string \| null	ne	HEAD repozitáře, když byl posuzován.
verdikt	RustdocVerdict → RustdocVerdict	ano	Verdikt.
důvod	string \| null	ne	Proč nebylo nic posouzeno, pokud nebylo.
počty	RustdocCounts → RustdocCounts	ano	Co se počítalo.
moduly	pole RustdocModuleRoute → RustdocModuleRoute	ano	Každý exportovaný modul knihovny s jeho stránkou, v kanonickém pořadí: jediné mapování modul–cesta, které čte každý konzument. Odvozeno z crate, takže se odpovídá i tehdy, když strom chybí.
zjištění	pole RustdocFinding → RustdocFinding	ano	Každý nález, v kanonickém pořadí.

Používá quality.rustdoc

RustdocVerdict

"clean" | "findings" | "no_tree"

Čím byl strom posouzen.

cleanStrom obsahuje každou stránku, kterou crate odvozuje, a nic chybného se nenašlo.
findingsAlespoň jeden nález platí.
no_treeNic nešlo posoudit: strom, nebo crate, který jej dokumentuje, chybí. Nikdy ne průchod — producent neběžel a kontrola, která nevidí svůj předmět, to říká.

Používá RustdocReport

Porušení

object

Jedno zjištění: co, kde, proč a co s tím.

vlastnost	typ	povinné	popis
kód	ViolationCode → ViolationCode	ano	Stabilní kód.
závažnost	QualitySeverity → QualitySeverity	ano	Jak je to zlé.
pravidlo	string	ano	Kanonické id pravidla, které toto vyžaduje.
path	string	ano	Kde to je, relativně k repozitáři; prázdné, když se nález netýká souboru.
řádek	integer \| null	ne	Řádek, počítáno od 1; `None`, když se nález netýká řádku.
symbol	string	ano	Úplná cesta položky, nebo příkaz, nebo id schopnosti: čeho se nález týká.
zpráva	string	ano	Jedna věta, specifická pro tento výskyt.
why	string	ano	Proč na tom záleží, z kódu.
náprava	string	ano	Co dělat, podle kódu.

Používá QualityReport

ViolationCode

Co je špatně, jako stabilní strojově čitelný kód.

Kódy jsou kontrakt mezi validátorem a vším za ním: anotacemi CI, filtry Cockpitu, kotvami dokumentace a agentem, který rozhoduje, co opravit. Kód se po vydání nikdy nepřejmenuje; pravidlo, které přestane existovat, si svůj kód odnese.

RUST_PUBLIC_MISSING_DOCSExportovaná položka nenese žádnou dokumentaci.
RUST_PUBLIC_THIN_DOCSDokumentace exportované položky neříká nic, co už neřekl její podpis.
RUST_PUBLIC_MISSING_EXAMPLEExportovaná položka, která nese chování, nemá spustitelný příklad.
RUST_EXAMPLE_NOT_EXECUTABLEKaždý příklad, který položka má, je ignoren nebo je prózou v ohraničeném bloku.
RUST_EXAMPLE_PLACEHOLDERPříklad nic netvrdí, nebo tvrdí něco, co platí pro jakýkoli program.
RUST_EXAMPLE_DOES_NOT_NAME_SUBJECTPříklad nikdy nejmenuje položku, kterou dokumentuje.
RUST_MODULE_MISSING_DOCSExportovaný modul nenese žádnou dokumentaci na úrovni modulu.
RUST_MODULE_MISSING_EXAMPLEExportovaný modul nemá spustitelný příklad na úrovni modulu.
RUST_MODULE_MISSING_BEHAVIOURAL_TESTŽádný test nejmenuje exportovaný modul a sám žádný nedeklaruje.
OPERATION_CLI_UNCLASSIFIEDPříkaz příkazové řádky není ani kanonická schopnost, ani klasifikován jako patřící jen příkazové řádce.
OPERATION_CLASSIFICATION_STALEPříkaz je klasifikován jako patřící pouze příkazové řádce a příkazová řádka jej už nemá.
OPERATION_CLASSIFICATION_CONFLICTPříkaz je klasifikován jako lokální a vázaný na schopnost: dvě odpovědi na jednu otázku.
OPERATION_MISSING_OPENAPISchopnost deklaruje HTTP routu a dokument OpenAPI ji nepopisuje.
OPERATION_PROJECTION_MISSINGSchopnost deklaruje projekci, kterou samotná projekce nenese.
OPERATION_PROJECTION_ORPHANProjekce nese položku, kterou registr neobsahuje.

Používá Violation