busfactor

busfactor

Every codebase has files that only one person really knows. If that person is away — on holiday, off sick, gone from the team — those files are the ones nobody can safely change. busfactor works out where that risk sits. You give it, for each file, who wrote it and how many commits each author made, plus who reviewed changes to it, and it gives back a factual map:

• Per-file entries — for every file, its total_commits, how many distinct authors it has, its top_author and that author's top_share of the file's commits, and external_reviewers: how many of its reviewers are not authors of the file. A review by one of the file's own authors does not count as external review, so a file checked only by the people who wrote it reads as never reviewed.
• Two flags, one list — a file is dominated when its top author's share reaches the threshold (0.8 by default), and never_reviewed when it has no external reviewers. A file that is both is at_risk, and at_risk_files collects exactly those paths. The list is a statement of fact about concentration and coverage; it carries no judgement about the people involved.
• Summary counts — how many files were analysed, how many are at risk, how many have a single author, and how many were never externally reviewed.

Duplicate author names inside one file are merged by summing their commits before anything is computed, and reviewer names are de-duplicated. The top-author share is rounded to four decimal places, and the domination check compares that rounded share — the number the report itself shows — against the threshold, so a file reported at exactly the threshold is always flagged dominated. Every list in the result is sorted ascending, so the same data always yields exactly the same map. Malformed input — a missing or empty file list, a duplicate path, an author with no commits — is a validation error naming the offending path (for example files[1].authors[0].commits must be an integer >= 1), and no partial map is produced. The computation is pure and local: no network, no configuration, no files read beyond the input you pass in.

CLI

npx @reneturcios/busfactor analyze --input args.json
npx @reneturcios/busfactor --version

args.json contains the full arguments object:

{
  "files": [
    { "path": "src/solo.ts", "authors": [{ "name": "amy", "commits": 10 }] },
    {
      "path": "src/shared.ts",
      "authors": [
        { "name": "amy", "commits": 5 },
        { "name": "bob", "commits": 5 }
      ],
      "reviewers": ["amy", "cleo"]
    }
  ]
}

reviewers defaults to [] per file, and threshold defaults to 0.8. Here src/solo.ts is single-author and unreviewed, while src/shared.ts is split evenly and was externally reviewed by cleo. The map is printed as JSON:

{
  "files": [
    {
      "path": "src/shared.ts",
      "total_commits": 10,
      "distinct_authors": 2,
      "top_author": "amy",
      "top_share": 0.5,
      "external_reviewers": 1,
      "never_reviewed": false,
      "dominated": false,
      "at_risk": false
    },
    {
      "path": "src/solo.ts",
      "total_commits": 10,
      "distinct_authors": 1,
      "top_author": "amy",
      "top_share": 1,
      "external_reviewers": 0,
      "never_reviewed": true,
      "dominated": true,
      "at_risk": true
    }
  ],
  "at_risk_files": ["src/solo.ts"],
  "summary": {
    "total_files": 2,
    "at_risk_count": 1,
    "single_author_count": 1,
    "never_reviewed_count": 1
  }
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/busfactor mcp

MCP client config:

{
  "mcpServers": {
    "busfactor": {
      "command": "npx",
      "args": ["-y", "@reneturcios/busfactor", "mcp"]
    }
  }
}

Tools

• analyze_bus_factor — Map single-author, never-reviewed files from authorship and review data.

  • files (array, required, at least one) — files as {path, authors, reviewers?} objects; path is unique across the set, each authors entry is a {name, commits} pair with at least 1 commit, and reviewers lists names that reviewed changes to the file
  • threshold (number, optional, default 0.8) — the top-author share at or above which a file counts as dominated by one author; must be > 0 and <= 1

  Returns {files, at_risk_files, summary}.

Docker

docker run -i ghcr.io/cloudcorprecords/busfactor
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/busfactor analyze --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios