HTTP API: rules

What a path a rule names actually is, decided by what drives it rather than by where it sits.

The corpus names two kinds and this distinction is the difference between a verdict and a mechanism. A case is driven by a runner, so an execution of it can be recorded and the repository can show that it passed. A gate is an executable check a CI gate runs as its own command, or a unit-test module (src/<module>/tests.rs) the gate running the crate's cargo test compiles: it refuses violations on every run, and this repository records no verdict for it, so what can be shown is the mechanism and not the result. Anything else a rule names is proof only in prose.

Example

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

What a rule declares about how strongly it binds.

The repository has exactly two, and they are not severities on a scale: blocking means a gate refuses the work, advisory means a reader is expected to have read it. A rule whose front matter says neither is reported as Class::Unknown rather than defaulted, because guessing here is how a blocking rule quietly becomes advice.

Example

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

How much of the rule corpus carries each part of a proof.

Every number here is counted from the tree. Nothing in this struct may be written down anywhere else: a hardcoded rule count is the defect this repository keeps rediscovering.

Example

Every number is counted from the tree; an empty corpus counts zero rather than reading as complete, which is what Coverage::default is for.

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

One rule, as the repository canonically declares it.

Example

Built by definitions from the index rather than by hand. Its ordering is the one the crate has, so a report over the same tree reads the same twice.

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);

One rule, with everything that proves it and everything that depends on it.

Example

What rules show answers: the proof, the rules either side of it in the dependency graph, and the one sentence saying what would make it proven.

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);

The enforcement block of a rule, read from x-majordomus.

Example

Read from front matter rather than built by hand; this is the shape a gated rule produces, and the mode is decided by what the block actually names.

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);

One rule whose declared class the proof does not support.

Example

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);

How a rule is enforced, as its own front matter declares it.

Example

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

One rule, joined to everything the repository can show about it.

Example

A RuleProof is what report produces per rule; satisfied is whether the state supports the class the rule declares, which is the whole question.

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");

What the repository can say about one rule's proof, as a whole.

Ordered strongest to weakest so that a summary sorted by this reads as a ranking. A rule's state is made from its parts' by crate::evidence::freshness::aggregate: a failing part makes it failing, and otherwise the weakest part that can carry proof decides.

Example

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

A rule named from somewhere else, with just enough to decide whether to follow it.

Example

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);

One test a rule names, joined to what was recorded against it.

Example

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);

The validator a dispatched rule names, and whether anything defines it.

A validator is not a path. validator: adr names the shell function mj_validate_adr, which the doctrine dispatcher calls; the tool finds it by scanning lib/, exactly as majordomus doctor does. Reading it as a path is a mistake worth recording here, because it is the one this type was introduced to fix: it makes every dispatched rule in the vendored package report as naming something that is not in the tree, which is the opposite of true — those are the best-enforced rules there are.

Example

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");

The whole rule corpus, verified.

Example

The whole corpus joined to the tree and the ledger. verdict is what the corpus can be said to prove; satisfied is only that there are no findings, and the two differ whenever a blocking rule has never been run.

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");

What the whole corpus can be said to prove, in one word, before any number is read.

satisfied answers a narrower question — are there findings — and a corpus in which no blocking rule was ever run has none, because not run, gated and reviewed are weaker states rather than defects (docs/DOCTRINE.md). Read alone, satisfied: true over such a corpus says "every rule is enforced" about a repository that has shown nothing. The verdict is the answer that cannot be read that way: it is proven only when every blocking rule is proven — a passing run recorded on a clean tree, at a commit that nothing but the evidence ledger has changed since. A rule whose inputs are merely unchanged is not that (ADR 0041), and leaves the corpus unproven.

Example

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
);

What one test proves: the reverse of RuleDetail.

Example

The reverse of rules show: what a test proves, and which rules would be left with no proof at all if it were deleted.

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);