HTTP API: commit

Where one path stands between the index and the working tree.

use majordomus_cli::commit::ChangeStage;
// ordered so that what would be in the next commit sorts first
assert!(ChangeStage::Staged < ChangeStage::Unstaged);
assert!(ChangeStage::Unstaged < ChangeStage::Untracked);

Why a commit was not judged.

use majordomus_cli::commit::{judge, CommitExemption, CommitPolicy, CommitSubject};
let v = judge(&CommitSubject::of("Merge pull request #1 from a/b"), &CommitPolicy::default());
assert_eq!(v.exempt, Some(CommitExemption::GitAuthored));

One commit a plan proposes. One commit a plan proposes: its message, its paths, and why those paths are one commit.

use majordomus_cli::commit::{plan::group, CommitGroup, ScopeVocabulary};
let mut v = ScopeVocabulary::default();
v.learn("commit", "src/commit", 40);
let g: Vec<CommitGroup> = group(&["src/commit/a.rs".into()], &v, &[]);
// the subject is empty on purpose: what a change did is the one thing no evidence in
// the tree can state
assert_eq!(g[0].message.header.subject, "");
assert_eq!(g[0].message.header.scope.as_deref(), Some("commit"));
assert!(g[0].rationale.contains("40 prior commit"), "{}", g[0].rationale);

The header of a commit message: its first line, taken apart.

word is the type as the author wrote it and kind is what that word names; they differ exactly when the word is not one of the eleven the convention defines, and keeping both is what lets a reader see wip(site): halfway through as its author typed it while a judge still reports that wip is not a type.

use majordomus_cli::commit::CommitHeader;
use majordomus_cli::release::ChangeKind;
let h = CommitHeader::parse("fix(plan): the fingerprint names what moved");
assert_eq!(h.word, "fix");
assert_eq!(h.kind, ChangeKind::Fix);
assert_eq!(h.scope.as_deref(), Some("plan"));
assert!(!h.breaking);
assert_eq!(h.subject, "the fingerprint names what moved");

A commit message taken apart: header, body, trailers.

use majordomus_cli::commit::CommitMessage;
let m = CommitMessage::parse("feat(a): a thing\n\nThe body.\n\nRefs: I1305\n");
assert_eq!(m.header.subject, "a thing");
assert_eq!(m.body, "The body.");
assert_eq!(m.trailers.len(), 1);

A plan over a working tree.

use majordomus_cli::commit::{CommitPlan, PlanFingerprint, WorkingTreeState};
let plan = CommitPlan {
    fingerprint: PlanFingerprint::of("/r/.git", "/r", &WorkingTreeState::default()),
    tree: WorkingTreeState::default(),
    groups: Vec::new(),
    diagnostics: Vec::new(),
};
assert!(plan.groups.is_empty(), "a clean tree proposes nothing");

One Key: value line in the trailer block at the end of a commit message.

use majordomus_cli::commit::CommitMessage;
use majordomus_cli::commit::CommitTrailer;
let m = CommitMessage::parse("fix(x): a thing\n\nWhy.\n\nRefs: I1305\n");
let t: &CommitTrailer = &m.trailers[0];
assert_eq!(t.key, "Refs");
assert_eq!(t.value, "I1305");

What the judge concluded: the message as it was parsed, whether anything of error severity was found, the exemption when git composed the subject rather than a person, and every finding in CommitRule::ALL order — which is the order the evidence for them appears in the message, so a person reads them in the order they would fix them.

use majordomus_cli::commit::{judge, CommitPolicy, CommitSubject, CommitVerdict};
let v: CommitVerdict = judge(&CommitSubject::of("update stuff"), &CommitPolicy::default());
assert!(!v.passed);
assert_eq!(v.findings[0].code, "commit.not_conventional");
assert_eq!(v.message.header.subject, "update stuff", "what was judged, not what was typed");

A range of history, judged. A range of history, judged in one pass.

use majordomus_cli::commit::verdict::HistoryReport;
let r = HistoryReport {
    range: "HEAD".into(),
    total: 1755,
    exempt: 561,
    failing: 54,
    commits: Vec::new(),
};
// a commit with nothing to say is counted and not listed: a report of a thousand
// passing commits is a report nobody reads
assert!(r.commits.is_empty());
assert_eq!(r.total - r.exempt, 1194);

One commit of the history, judged.

use majordomus_cli::commit::verdict::JudgedCommit;
// what a history report lists: only the commits that have something to say
let row = JudgedCommit {
    commit: "a1b2c3d4e".into(),
    subject: "update stuff".into(),
    passed: false,
    exempt: None,
    findings: Vec::new(),
};
assert!(!row.passed);

One path, and where it stands.

use majordomus_cli::commit::ChangeStage;
use majordomus_cli::commit::plan::PathChange;
// staged and modified again since: the commit would carry the staged half only
let c = PathChange {
    path: "src/a.rs".into(), stage: ChangeStage::Staged, status: "MM".into(), partial: true,
};
assert!(c.partial);

What a plan was derived from.

Compared, never trusted: a plan whose fingerprint differs from the tree in front of it describes a tree that no longer exists.

use majordomus_cli::commit::{PlanFingerprint, WorkingTreeState};
let f = PlanFingerprint::of("/repo/.git", "/repo", &WorkingTreeState::default());
assert_eq!(f.head, "unborn", "a repository with no commits says so");

Which scope a set of paths belongs to, and the evidence for it.

use majordomus_cli::commit::{ScopeSuggestion, ScopeVocabulary};
let mut v = ScopeVocabulary::default();
// two scopes with equal claim to one directory: reported, never broken silently
v.learn("a", "src", 7);
v.learn("b", "src", 7);
let s: ScopeSuggestion = v.suggest(&["src/x.rs".into()]).expect("a tie");
assert!(s.ambiguous);

One scope the history uses, and how much.

use majordomus_cli::commit::scopes::ScopeUse;
let u = ScopeUse { scope: "commit".into(), commits: 40, directories: vec!["src/commit".into()] };
assert_eq!(u.commits, 40);

The vocabulary as observed, with what was observed.

use majordomus_cli::commit::ScopeVocabulary;
// an empty vocabulary knows nothing and says so, rather than guessing
let v = ScopeVocabulary::default();
assert!(!v.knows("anything"));
assert!(v.words().is_empty());

The vocabulary, with the policy that reads it.

use majordomus_cli::capability::builtin::commit::ScopesReport;
use majordomus_cli::commit::ScopeVocabulary;
let r = ScopesReport { vocabulary: ScopeVocabulary::default(), sample: 1500 };
assert_eq!(r.sample, majordomus_cli::commit::scopes::SAMPLE);

What git says about the working tree right now.

use majordomus_cli::commit::WorkingTreeState;
let clean = WorkingTreeState::default();
assert!(clean.is_clean());
assert!(clean.staged().is_empty());