HTTP API: evidence

Jedno tvrzení se vším, co o jeho důkazu repozitář může říct, a cesta zpět k testu, který jej nese.

Důkaz je do odpovědi zploštěn, takže klient čte jedno tvrzení, ne obal důkazu kolem něj; provedení a ostatní tvrzení, která tentýž test dokazuje, leží vedle něj.

use majordomus_cli::capability::builtin::evidence::ClaimEvidence;
use majordomus_cli::evidence::ClaimProof;

let proof: ClaimProof = serde_json::from_value(serde_json::json!({
    "id": "evidence-both-directions",
    "claim": "a claim and its test answer for each other",
    "status": "guaranteed",
    "source": null,
    "implementation": null,
    "test_path": "test/cases/84_distribution_model.sh",
    "test": "suite:84_distribution_model",
    "state": "not_run",
    "meaning": "no run of this test has been recorded",
    "execution": null,
    "changed": [],
    "reproduce": "bash test/run.sh 84_distribution_model"
}))
.unwrap();

let answer = ClaimEvidence {
    proof,
    executions: Vec::new(),
    also_proves: vec!["evidence-record-is-not-networked".to_string()],
};
let json = serde_json::to_value(&answer).unwrap();
assert_eq!(json["id"], "evidence-both-directions");
assert!(json.get("proof").is_none(), "the claim is flattened in, not nested");
assert_eq!(json["also_proves"], serde_json::json!(["evidence-record-is-not-networked"]));
// a list even where the ledger keeps one: retention is a decision that may change,
// and a client that read a bare object would break when it did
assert_eq!(json["executions"], serde_json::json!([]));

Jedno tvrzení spojené se vším, co o něm repozitář skutečně zaznamenal.

Vlastní pole tvrzení se nesou doslova vedle odvozených, aby čtenář, který stavu nevěří, mohl spojení ověřit, místo aby ho přijal.

use majordomus_cli::evidence::{ClaimProof, ProofState};

let proof = ClaimProof {
    id: "scope-integrity".into(),
    claim: "a commit outside the task's scope is refused".into(),
    status: "guaranteed".into(),
    source: Some("docs/SCOPE.md".into()),
    implementation: Some("apps/majordomus-cli/src/scope.rs".into()),
    test_path: Some("test/cases/07_scope.sh".into()),
    test: Some("suite:07_scope".into()),
    state: ProofState::NotRun,
    meaning: ProofState::NotRun.meaning().to_string(),
    execution: None,
    changed: vec![],
    detail: None,
    reproduce: Some("bash test/run.sh 07_scope".into()),
};

let json = serde_json::to_value(&proof).unwrap();
// `changed` is emitted empty rather than omitted: a client must not have to tell
// "no file changed" from "the server did not say"
assert_eq!(json["changed"], serde_json::json!([]));
// an execution that does not exist is absent, not a null standing in for one
assert!(json.get("execution").is_none());
// and so is a detail the state did not need
assert!(json.get("detail").is_none());
assert_eq!(json["meaning"], serde_json::json!(ProofState::NotRun.meaning()));

Příklad

ClaimProof vytváří report; jeho state je celá odpověď a jeho meaning je ta odpověď ve větě, formulovaná jednou pro každý povrch.

use majordomus_cli::evidence::{report, ClaimProof, 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 proofs: &[ClaimProof] = &r.claims;
assert!(proofs.is_empty(), "a synthetic tree declares no claims");

Tvrzení, jehož deklarovaný stav důkazy nepodporují.

Může ho vyprodukovat jen tvrzení guaranteed: ostatní stavy už říkají, že aktuální důkaz není to, co tvrdí. Nález říká, co bylo tvrzeno, co místo toho podporují důkazy a — kde by to rozhodlo spuštění něčeho — co spustit.

use majordomus_cli::evidence::{Finding, ProofState};

let finding = Finding {
    claim: "scope-integrity".into(),
    status: "guaranteed".into(),
    state: ProofState::NotRun,
    reason: "the claim guarantees a behaviour and names a test, and no run of that \
             test has ever been recorded"
        .into(),
    reproduce: Some("bash test/run.sh 07_scope".into()),
};

// the gap is the finding: what the matrix declares against what the ledger holds
assert_ne!(finding.status, finding.state.label());
assert!(finding.reproduce.unwrap().starts_with("bash test/run.sh"));

Příklad

use majordomus_cli::evidence::{Finding, ProofState};
let f = Finding {
    claim: "some-claim".into(),
    status: "guaranteed".into(),
    state: ProofState::NotRun,
    reason: "the claim names a test nobody has run".into(),
    reproduce: Some("bash test/run.sh 07_scope".into()),
};
assert_eq!(f.state, ProofState::NotRun);

Čím ledger je a zda tam vůbec je.

Zpráva, která by neřekla, odkud pocházejí její důkazy, by žádala o víru. Toto je původ celé zprávy: soubor, kolik drží, jak starý je nejnovější záznam a proti kterým commitům se kdy cokoli zaznamenalo.

use majordomus_cli::evidence::{Ledger, LedgerSummary, LEDGER_PATH};

let summary: LedgerSummary = Ledger::empty().summary();
assert_eq!(summary.path, LEDGER_PATH);
assert!(!summary.present, "a ledger holding nothing has recorded nothing");
assert_eq!(summary.executions, 0);
assert!(summary.newest.is_none());
assert!(summary.commits.is_empty());

Příklad

use majordomus_cli::evidence::LedgerSummary;
let s = LedgerSummary {
    path: ".ai/repo/evidence/ledger.json".into(),
    present: false,
    executions: 0,
    newest: None,
    commits: vec![],
};
assert!(!s.present, "a repository that recorded nothing says so");

K čemu byl report posuzován: revize, její strom a běhy, které checkout drží a které vlastní kniha revize neobsahuje.

Verdikt je vždy verdikt k něčemu. evidence show posuzuje pracovní strom; evidence show --presented HEAD posuzuje checkoutnutý commit tak, jak byl commitnut, z ledgeru v něm commitnutého — což je čtení, které potřebuje web sestavený z toho commitu.

use majordomus_cli::evidence::{PresentedRevision, TreeState};

let here = PresentedRevision {
    revision: "working_tree".into(),
    tree: TreeState::Dirty,
    uncommitted: vec![],
};
let json = serde_json::to_value(&here).unwrap();
assert_eq!(json["tree"], "dirty");
// nothing held uncommitted is absent, not an empty list to read past
assert!(json.get("uncommitted").is_none());

Celý spojený obraz: každé tvrzení matice vůči každému zaznamenanému provádění.

Co schopnost odpovídá, co kontrola posuzuje a co web vykresluje, je tatáž hodnota; součty a nálezy se odvozují z tvrzení, nikdy se nepočítají dvakrát.

use majordomus_cli::evidence::{
    EvidenceReport, Finding, Ledger, PresentedRevision, ProofState, Subject, TreeState,
};

let mut report = EvidenceReport {
    head: None,
    working_tree: "unknown".into(),
    presented: PresentedRevision {
        revision: "working_tree".into(),
        tree: TreeState::Unknown,
        uncommitted: vec![],
    },
    ledger: Ledger::empty().summary(),
    subject: Subject { examined: 0, complete: true, excluded: vec![] },
    claims: vec![],
    totals: Default::default(),
    findings: vec![],
};
assert!(report.satisfied(), "nothing claimed, so nothing unsupported");

// and the same report over a subject it could not wholly read is not a pass
let mut partial = report.clone();
partial.subject.complete = false;
assert!(!partial.satisfied(), "an absent answer is not a clean one");

report.findings.push(Finding {
    claim: "scope-integrity".into(),
    status: "guaranteed".into(),
    state: ProofState::Failing,
    reason: "the claim guarantees a behaviour whose test most recently failed".into(),
    reproduce: None,
});
// one unsupported guarantee is enough: the gate is not a proportion
assert!(!report.satisfied());

Příklad

Celá matice spojená s účetní knihou. satisfied je pravda, když žádné tvrzení nedeklaruje záruku, kterou zaznamenané důkazy nepodporují.

use majordomus_cli::evidence::{report, EvidenceReport, Ledger};
use majordomus_cli::synthetic::SyntheticRepository;
let repo = SyntheticRepository::small().unwrap();
let ledger = Ledger::load(repo.root()).unwrap();
let r: EvidenceReport = report(&repo.index().unwrap(), &ledger);
assert!(r.satisfied(), "no claim, so no unsupported guarantee");

Zda report viděl celý svůj předmět.

Verdikt nad maticí, kterou index tiše zmenšil, je selhání, které tento repozitář potkal čtyřikrát za jediný den: objekt je vyloučen, každá projekce menšího indexu je věrnou projekcí a každá kontrola vytiskne pravdivé tvrzení o polovině, kterou vidí. Kontrola aktuálnosti odpoví „vzniklo to z tohoto stromu“, ale nedokáže odpovědět „viděl generátor všechno, co v něm je“, takže odpověď musí nést vlastní jmenovatel.

use majordomus_cli::evidence::Subject;
let whole = Subject { examined: 149, complete: true, excluded: vec![] };
assert!(whole.complete);

let partial = Subject {
    examined: 148,
    complete: false,
    excluded: vec!["docs/CLAIMS.yaml: unknown_key".into()],
};
assert!(!partial.complete, "a shrunken index must not report a clean verdict");

Zda strom byl commitem, na kterém sedí: tři slova, která ledger a git už používají, typovaná.

unknown není mírnější clean. Je to to, co se zaznamená, když se git nedalo zeptat, a nevědět není důkaz, takže každé zdejší pravidlo to bere jako nečisté.

use majordomus_cli::evidence::freshness::TreeState;

assert_eq!(TreeState::parse("clean"), TreeState::Clean);
assert_eq!(TreeState::parse("dirty"), TreeState::Dirty);
// a word nobody wrote down is not a clean tree
assert_eq!(TreeState::parse("spotless"), TreeState::Unknown);
assert_eq!(TreeState::Dirty.as_str(), "dirty");
assert_eq!(serde_json::to_value(TreeState::Unknown).unwrap(), "unknown");

Jeden test a co dokazuje.

Opačný směr ClaimEvidence, čtený od konce testu: jeho identita, jeho zdroj a zda je tento zdroj stále tím, který běžel, příkaz, který ho spustí znovu, a každé tvrzení, které ho jmenuje.

use majordomus_cli::capability::builtin::evidence::TestEvidence;
use majordomus_cli::evidence::TestId;

let id = TestId::of("apps/majordomus-cli/tests/why.rs").unwrap();
let answer = TestEvidence {
    test: id.as_string(),
    runner: id.runner,
    source: id.source(),
    present: true,
    reproduce: id.reproduce(),
    execution: None,
    digest_matches: None,
    proves: Vec::new(),
};
assert_eq!(answer.test, "crate:why");
assert_eq!(answer.reproduce, "cargo test --test why");

// nothing recorded: the two provenance keys are absent rather than null, so "no
// execution" cannot be read as an execution that said nothing
let json = serde_json::to_value(&answer).unwrap();
assert!(json.get("execution").is_none() && json.get("digest_matches").is_none());
assert_eq!(json["proves"], serde_json::json!([]));