HTTP API: rules

Čím cesta jmenovaná pravidlem skutečně je, rozhodnuto tím, co ji pohání, ne tím, kde leží.

Korpus jmenuje dva druhy a toto rozlišení je rozdílem mezi verdiktem a mechanismem. Případ řídí runner, takže jeho provedení lze zaznamenat a repozitář může ukázat, že prošel. Kontrola je spustitelná kontrola, kterou CI kontrola spouští jako vlastní příkaz, nebo modul unit testů (src/<module>/tests.rs), který kompiluje kontrola spouštějící cargo test crate: odmítá porušení při každém běhu a tento repozitář pro ni neeviduje žádný verdikt, takže lze ukázat mechanismus, ne výsledek. Cokoli jiného, co pravidlo jmenuje, je důkazem jen v próze.

Příklad

use majordomus_cli::rules::ArtifactKind;
assert_eq!(ArtifactKind::Case.label(), "case");
assert_eq!(ArtifactKind::Gate.label(), "gate");

Co pravidlo deklaruje o tom, jak silně zavazuje.

Repozitář má právě dva a nejsou to závažnosti na škále: blocking znamená, že kontrola práci odmítne, advisory znamená, že se čeká, že to čtenář přečetl. Pravidlo, jehož front matter neříká ani jedno, se hlásí jako Class::Unknown, místo aby dostalo výchozí hodnotu, protože hádání je přesně to, jak se blokující pravidlo nenápadně stane radou.

Příklad

use majordomus_cli::rules::Class;
assert_eq!(Class::Blocking.label(), "blocking");
assert_eq!(Class::parse("advisory"), Class::Advisory);

Kolik korpusu pravidel nese každou část důkazu.

Každé zdejší číslo se počítá ze stromu. Nic v této struktuře nesmí být zapsáno nikde jinde: napevno zapsaný počet pravidel je vada, kterou tento repozitář opakovaně znovu objevuje.

Příklad

Každé číslo se počítá ze stromu; prázdný korpus se počítá jako nula, nečte se jako úplný, k čemuž slouží Coverage::default.

use majordomus_cli::rules::Coverage;
let c = Coverage::default();
assert_eq!(c.rules, 0);
assert_eq!(c.review_only, 0);

Jedno pravidlo, jak ho repozitář kanonicky deklaruje.

Příklad

Sestaveno pomocí definitions z indexu, ne ručně. Jeho řazení je to, které crate má, takže zpráva nad týmž stromem se čte dvakrát stejně.

use majordomus_cli::rules::{Class, RuleDefinition};
#### use majordomus_cli::rules::{Enforcement, Mode};
let d = RuleDefinition {
    id: "project.scope-is-declared".into(),
    identity: "project.scope-is-declared@1".into(),
    uri: "majordomus://rule/project.scope-is-declared@1".into(),
    version: 1,
    title: "Scope is declared".into(),
    description: None,
    statement: None,
    status: "active".into(),
    class: Class::Blocking,
    namespace: "project".into(),
    depends_on: vec![],
    tags: vec![],
    path: ".ai/repo/rules/project/scope-is-declared.v1.md".into(),
    enforcement: Enforcement {
        mode: Mode::Declarative, validator: None, category: None, exit_code: None,
        enforced_by: None, tests: vec![], reviewed_because: None,
    },
};
assert_eq!(d.class, Class::Blocking);

Jedno pravidlo, se vším, co ho dokazuje, a vším, co na něm závisí.

Příklad

Co odpovídá rules show: důkaz, pravidla po obou stranách v grafu závislostí a jedna věta říkající, co by to prokázalo.

use majordomus_cli::capability::builtin::rules::RuleSummary;
use majordomus_cli::rules::{Class, RuleState};
// a RuleDetail carries these summaries for depends_on and required_by
let dep = RuleSummary {
    id: "project.dep".into(), title: "Dep".into(),
    class: Class::Blocking, state: RuleState::NotRun,
};
assert_eq!(dep.class, Class::Blocking);

Blok vynucování pravidla, čtený z x-majordomus.

Příklad

Čteno z front matter místo ručního sestavení; to je tvar, který vytváří kontrolované pravidlo, a režim se určuje tím, co blok skutečně pojmenovává.

use majordomus_cli::rules::{Enforcement, Mode};
let e = Enforcement {
    mode: Mode::Gated,
    validator: None,
    category: None,
    exit_code: None,
    enforced_by: None,
    tests: vec!["test/cases/07_scope.sh".into()],
    reviewed_because: None,
};
assert_eq!(e.mode, Mode::Gated);

Jedno pravidlo, jehož deklarovanou třídu důkaz nepodporuje.

Příklad

use majordomus_cli::rules::{Class, Finding, RuleState};
let f = Finding {
    rule: "project.x".into(),
    class: Class::Blocking,
    state: RuleState::Dangling,
    reason: "it names a path that is not in the tree".into(),
    reproduce: "scripts/ci/rule-proof-check".into(),
};
assert_eq!(f.state, RuleState::Dangling);

Jak se pravidlo vynucuje, tak jak to deklaruje jeho vlastní front matter.

Příklad

use majordomus_cli::rules::Mode;
assert_eq!(Mode::Dispatched.label(), "dispatched");
assert_eq!(Mode::Declarative.label(), "declarative");

Jedno pravidlo, spojené se vším, co o něm repozitář umí ukázat.

Příklad

RuleProof je to, co report vytváří pro každé pravidlo; satisfied je to, zda stav podporuje třídu, kterou pravidlo deklaruje, což je celá otázka.

use majordomus_cli::rules::{report, RuleProof, RuleState};
use majordomus_cli::evidence::Ledger;
use majordomus_cli::synthetic::SyntheticRepository;
let repo = SyntheticRepository::small().unwrap();
let ledger = Ledger::load(repo.root()).unwrap();
let r = report(&repo.index().unwrap(), &ledger);
let first: &RuleProof = &r.rules[0];
assert_eq!(first.state, RuleState::Unproven);
assert!(first.satisfied, "an advisory rule owes no executable proof");

Co o důkazu jednoho pravidla dokáže repozitář říct jako celek.

Řazeno od nejsilnějšího k nejslabšímu, aby se shrnutí seřazené podle toho čte jako žebříček. Stav pravidla se skládá ze stavů jeho částí pomocí crate::evidence::freshness::aggregate: selhávající část ho činí selhávajícím, jinak rozhoduje nejslabší část, která může nést důkaz.

Příklad

use majordomus_cli::rules::RuleState;
assert!(RuleState::Proven < RuleState::Stale);
assert!(RuleState::Stale.passing());
assert!(!RuleState::Dangling.passing());

Pravidlo jmenované odjinud, s právě tolika údaji, aby se dalo rozhodnout, zda se jím řídit.

Příklad

use majordomus_cli::capability::builtin::rules::RuleSummary;
use majordomus_cli::rules::{Class, RuleState};
let s = RuleSummary {
    id: "project.x".into(),
    title: "X".into(),
    class: Class::Advisory,
    state: RuleState::Reviewed,
};
assert_eq!(s.state, RuleState::Reviewed);

Jeden test, který pravidlo jmenuje, spojený s tím, co bylo proti němu zaznamenáno.

Příklad

use majordomus_cli::rules::{ArtifactKind, TestProof};
use majordomus_cli::evidence::ProofState;
let t = TestProof {
    path: "test/cases/07_scope.sh".into(),
    kind: ArtifactKind::Case,
    present: true,
    test: Some("suite:07_scope".into()),
    state: ProofState::NotRun,
    meaning: ProofState::NotRun.meaning().into(),
    execution: None,
    reproduce: Some("bash test/run.sh 07_scope".into()),
    gates: vec!["shell-suite".into()],
};
assert_eq!(t.kind, ArtifactKind::Case);

Validátor, který odeslané pravidlo jmenuje, a zda jej něco definuje.

Validátor není cesta. validator: adr jmenuje shellovou funkci mj_validate_adr, kterou volá dispečer doktrín; nástroj ji najde skenováním lib/, přesně jako majordomus doctor. Číst ji jako cestu je chyba, kterou stojí za to zde zaznamenat, protože je to ta, kterou tento typ měl opravit: způsobí, že každé dispatchované pravidlo ve vendorovaném balíčku hlásí, že jmenuje něco, co ve stromu není, což je opak pravdy — to jsou nejlépe vynucovaná pravidla, jaká existují.

Příklad

use majordomus_cli::rules::ValidatorRef;
let v = ValidatorRef {
    name: "adr".into(),
    function: "mj_validate_adr".into(),
    defined_in: Some("lib/adr.sh".into()),
    present: true,
};
assert_eq!(v.function, "mj_validate_adr");

Celý korpus pravidel, ověřený.

Příklad

Celý korpus spojený se stromem a ledgerem. verdict je to, co lze o korpusu říct, že dokazuje; satisfied je jen to, že nejsou žádné nálezy, a obojí se liší, kdykoli blokující pravidlo nebylo nikdy spuštěno.

use majordomus_cli::rules::{RulesReport, RulesVerdict};
let r = RulesReport {
    head: None,
    working_tree: "clean".into(),
    verdict: RulesVerdict::Unproven,
    rules: vec![],
    states: Default::default(),
    coverage: Default::default(),
    findings: vec![],
    satisfied: true,
};
assert!(r.satisfied());
assert_ne!(r.verdict, RulesVerdict::Proven, "no findings is not proof");

Co lze o celém korpusu říci, že dokazuje, jedním slovem, dřív než se přečte jakékoli číslo.

satisfied odpovídá na užší otázku — jsou zde zjištění — a korpus, ve kterém nikdy neběželo žádné blokující pravidlo, žádná nemá, protože not run, gated a reviewed jsou slabší stavy, nikoli vady (docs/DOCTRINE.md). Čteno samo, satisfied: true nad takovým korpusem říká „každé pravidlo je vynucováno“ o repozitáři, který nic neprokázal. Verdikt je odpověď, kterou takto číst nelze: je proven jen tehdy, když je každé blokující pravidlo proven — úspěšný běh zaznamenaný na čistém stromě, na commitu, který od té doby nezměnilo nic než kniha důkazů. Pravidlo, jehož vstupy se prostě nezměnily, to není (ADR 0041) a nechává korpus unproven.

Příklad

use majordomus_cli::rules::{RuleState, RulesVerdict};
// a corpus with a finding is failing, whatever else is true of it
assert_eq!(RulesVerdict::of([RuleState::Proven], true), RulesVerdict::Failing);
// one blocking rule never run is enough to leave the corpus unproven
assert_eq!(
    RulesVerdict::of([RuleState::Proven, RuleState::NotRun], false),
    RulesVerdict::Unproven
);
assert_eq!(RulesVerdict::of([RuleState::Proven], false), RulesVerdict::Proven);
// a pass whose inputs are merely unchanged is not proven
assert_eq!(
    RulesVerdict::of([RuleState::Proven, RuleState::InputsUnchanged], false),
    RulesVerdict::Unproven
);

Co dokazuje jeden test: opak RuleDetail.

Příklad

Opak rules show: co test dokazuje a která pravidla by zůstala bez jakéhokoli důkazu, kdyby byl smazán.

use majordomus_cli::capability::builtin::rules::TestSubjects;
let t = TestSubjects {
    test: Some("suite:07_scope".into()),
    path: "test/cases/07_scope.sh".into(),
    present: true,
    reproduce: Some("bash test/run.sh 07_scope".into()),
    proves: vec![],
    sole_proof_of: vec![],
};
assert!(t.present);