Kvalita veřejného API

Čemu je vystavený exportovaný povrch Rust crate, jak se měří a co dělat, když kontrola řekne ne.

Pravidla jsou project.rust-public-api-quality a project.operation-transport-parity; rozhodnutí za nimi je ADR 0023. Tato stránka je pracovní reference: pravidla říkají proč, tady je jak.

Jeden příkaz

majordomus quality report              # every finding, grouped by code, with the remedy
majordomus quality report --summary    # the counts alone
majordomus quality report --format json
majordomus quality report --code RUST_MODULE_MISSING_EXAMPLE
majordomus quality report --path apps/majordomus-cli/src/web

Kód 0 končí, když nic nestojí mimo základní stav, jinak 10 — kód, který používá každý nesplněný kontrakt v tomto spustitelném souboru. JSON a vykreslení v terminálu jsou dvě čtení jednoho provedení, takže se nemohou rozcházet ve výsledku.

Kontrola rust-quality úlohy structure spouští první řádek, stejně jako scripts/rust-check: nejprve ve výchozím režimu, před formátem, lintem a testy, a samostatně s scripts/rust-check --quality. Změna, která přidá nebo rozšíří exportovanou položku, spustí to druhé před pushem a narazí na nález, který by tam vytiskla úloha structure, na vlastním počítači, a ne na konci běhu CI.

Totéž měření odpovídá na GET /api/v1/quality, jako nástroj MCP majordomus_quality a zdroj majordomus://quality a na stránce Quality Cockpitu. Je to schopnost jako každá jiná; nic z toho seznamu není druhou implementací.

Na co se ptá a čeho

Poslední dva řádky nejsou výjimky, které někdo udělil. Odvozují se z druhu a tvaru položky a zpráva je vypíše s důvodem, takže to, co se nevyžaduje, je viditelné stejně jako to, co se vyžaduje. Žádný soubor výjimek neexistuje.

Exportováno znamená to, co znamená rustc: deklarováno pub, v řetězci modulů pub od kořene crate, nebo vyneseno z privátního pub use. Položka pub v privátním modulu se neměří, což je první, po čem sáhnout, když kontrola žádá příklad, který psát nechcete.

Co se počítá jako příklad

Ohraničený blok se počítá, když platí všechny tři:

1. Toolchain to kompiluje. Žádné ignore. no_run se počítá — rozdíl je v tom, zda se to kompilovalo, ne zda se to spustilo. Blok ```text je próza v rámečku.
2. Jmenuje položku, kterou dokumentuje. Příklad Capability, který nikdy nepíše Capability, je důkaz o něčem jiném.
3. Tvrdí něco, co by mohlo být nepravdivé. unwrap, expect a ? jsou aserce, protože selhání kterékoli z nich způsobí selhání doctestu. assert!(true), assert_eq!(1, 1) a assert_eq!(2 + 2, 4) nejsou.

Položka s jedním skutečným příkladem a třemi diagramy je čistá: rozhoduje nejlepší blok.

Když kontrola řekne ne

Každý nález nese svůj kód, pravidlo, které jej vyžaduje, soubor a řádek, symbol, proč na něm záleží a co dělat:

RUST_PUBLIC_MISSING_EXAMPLE  (3 finding(s))
  rule        project.rust-public-api-quality@1
  why         prose about behaviour drifts; an executable example cannot, because the toolchain runs it
  remedy      add a ``` block that calls the item and asserts the result; or reduce the
              item's visibility to pub(crate) if no consumer needs it
  apps/majordomus-cli/src/graph.rs:42: … majordomus_cli::graph::build — …

Druhá polovina té nápravy je ta, na kterou lidé zapomínají. Tento crate je publish = false: jeho spotřebiteli jsou jeho vlastní binárka, jeho testy, jeho benchmarky a jeho příklady v dokumentaci. Položka, kterou žádný z nich nejmenuje, není API a pub(crate) je úplnou odpovědí na nález.

Kódy

Kódy jsou stabilní. Žádný se po vydání nikdy nepřejmenuje.

Západka

.ai/repo/rust-quality-baseline.txt zaznamenává nálezy, které platily, když pravidlo přistálo. Kontrola selže pro nález, který v něm není, takže dluh se může zmenšovat a nemůže růst; a selže pro položku jmenující nález, který už neexistuje, takže splacený dluh musí ze souboru zmizet.

Klíče jsou CODE<TAB>path<TAB>symbol. Řádek záměrně není součástí klíče: nález, který se v souboru posune dolů, když se něco nad ním upraví, je stejným nálezem, a základní linie klíčovaná řádkem by z každé nesouvisející úpravy udělala nový dluh.

majordomus quality report --write-baseline

je jediné, co jej zapisuje, a je to záměrný akt. Spusťte jej, když jste dluh splatili, ne když jste našli nový dluh — celý smysl je v tom, že nový dluh selže. Pravidlo je dokončeno, když je soubor prázdný a odstraněn.

Přidání příkazu: zlatá cesta

Příkaz je projekce schopnosti, nebo říká, proč není. Obojí se kontroluje.

Schopnost — běžný případ a ten, který vám dá všechny projekce najednou:

1. Deklarujte typovaný vstup a výstup tam, kde je modul vidí, odvoďte serde::Serialize, serde::Deserialize a schemars::JsonSchema a implementujte BenchmarkCases pro vstup.
2. Napište handler: fn (&Context, Input) -> Result<Output, CapabilityError>.
3. Přidejte capability! { … } do module() modulu a deklarujte expozice, které chce — včetně cli: Some(CliExposure { path: vec!["thing".into(), "show".into()] }).
4. Ve stejném souboru ověřte, že deklarace dává identitu a projekce, které tvrdí (project.rust-command-tested-in-file).
5. Deklarujte příkaz clap v src/cli.rs a vyvolejte ho přes Context::execute(<id>, input) — příkaz vlastní vykreslení a nic jiného.
6. majordomus generate obnoví commitnuté projekce.

MCP, HTTP, OpenAPI, Swagger, Cockpit, cíle měření výkonu a generovaná reference následují z kroku 3. Nic jiného se nikde neregistruje.

Není schopnost — přidejte položku do cli::LOCAL v src/cli/local.rs s jednou z hodnot:

RendersCapability je zkontrolováno: schopnost musí existovat a musí odpovídat přes HTTP, takže operace skutečně je v API a příkaz je skutečně jejím vykreslením. Neexistuje žádný důvod znamenající zatím nepromítnuto a je to záměr.

Kde jsou části

src/quality/source.rs   the crate as a syntax tree: what is exported, where, with what docs
src/quality/policy.rs   what an item owes, and what counts as having paid it
src/quality/parity.rs   the registry against MCP, HTTP, OpenAPI and the command line
src/quality/report.rs   one measurement: counts and findings, sorted, deterministic
src/quality/model.rs    the vocabulary: codes, severities, the report's shape
src/cli/local.rs        why a command is not a capability
src/capability/builtin/quality.rs   the capability every projection reads
tests/quality.rs        the ratchet, and one fixture per way of failing

Měření je deterministické a nepotřebuje síť: čtení souborů je jeho jediný I/O a dva běhy nad jedním stromem dávají shodné zprávy.