Module bus_factor 

Available on crate feature vcs-git only.

Directory- and repo-level bus factor (a.k.a. truck factor) over a change-history walk, via the Avelino Degree-of-Authorship (DoA) heuristic (issue #332).

Where score ranks files and ownership_top_share captures concentration within one file, the bus factor measures concentration across a set of files: the minimum number of developers whose departure would leave more than a configurable fraction of the set without a knowledgeable maintainer.

The Avelino DoA heuristic

Avelino, Passos, Hora & Valente, A Novel Approach for Estimating Truck Factors (ICPC 2016), score each developer’s authorship of each file with a regression fitted on a manually-validated corpus:

DOA(d, f) = 3.293 + 1.098·FA + 0.164·DL − 0.321·ln(1 + AC)

where, for developer d and file f:

• FA (first authorship) is 1 when d created f, else 0;
• DL (deliveries) is the number of changes d made to f;
• AC (accepted changes) is the number of changes other developers made to f.

A developer is an author (authority) of f when their DoA, normalised by the file’s maximum DoA, is at least DOA_NORMALIZED_THRESHOLD (0.75 in the paper). The truck factor is then computed greedily: repeatedly remove the developer who authors the most still-covered files until more than coverage_threshold (default DEFAULT_COVERAGE_THRESHOLD, 0.5 per Avelino) of the files are orphaned (have no remaining author). The number of developers removed is the bus factor.

Relation to the issue’s restatement

Issue #332 restates the formula as N₁·FA + N₂·ln(1+DL) + N₃·ln(1+AC). This module uses the paper’s published, validated coefficients (linear DL, not logged), because the issue also pins “thresholds from the paper”: the fitted 0.164 DL coefficient is only meaningful against a linear DL term, so logging it would mis-apply the regression. Normalisation makes the score scale-free regardless, so a single prolific author still dominates their file.

The result is ordinal-but-actionable

Unlike the per-file risk_score, the bus factor is a small integer with a direct reading: “this many key departures abandon the subsystem”. It still inherits the heuristic’s caveats — a young repo, or one with many single-author files, skews it downward (every file has exactly one author, so one departure orphans it). Any change to the formula, thresholds, or the grouping must bump BUS_FACTOR_SCHEMA_VERSION.

Co-authorship and windows

DL counts every commit a developer participated in (author plus Co-authored-by trailers), matching how ownership_top_share already credits edits, so a co-authored commit credits each participant one delivery. FA and the whole computation see only the history within the long window, so “first authorship” means the earliest observed commit, not necessarily the file’s true creation (true creation is the full-history follow-up, #329). Bot identities are filtered upstream, before authorship ever reaches this module.

Structs

AuthorContribution

One developer’s authorship inputs for a single file.

BusFactor

The full bus-factor aggregate: repo-level plus per-directory.

DirectoryBusFactor

Bus factor for one directory grouping.

FileAuthorship

One file’s complete authorship, the unit the aggregate consumes.

GroupBusFactor

Bus factor for one set of files (the repo, or one directory).

VcsAggregate

The vcs_aggregate block: whole-walk aggregates surfaced alongside the per-file vcs data. A wrapper so future aggregates can join the bus factor without another top-level field.

Constants

BUS_FACTOR_SCHEMA_VERSION

Output-shape / algorithm version for the bus-factor aggregate. Bump on any change to the formula, thresholds, grouping, or serialized fields.

DEFAULT_COVERAGE_THRESHOLD

Default fraction of files that must be orphaned for the greedy removal to stop — the Avelino coverage threshold (0.5).

DOA_NORMALIZED_THRESHOLD

Normalised-DoA threshold above which a developer counts as an author of a file (the paper’s 0.75). A file’s top contributor always reaches 1.0, so every file with any history has at least one author.

Functions

compute

Compute the bus-factor aggregate over every file’s authorship.