npm Package · Developer Tooling
Package v2.2.0 · MITgit-contributor-stats
CLI and library for Git contributor and activity analytics, with charts and reports.
My role · Author & Maintainer
Overview
A Node.js CLI and importable TypeScript library that turns local Git history into contributor and activity analytics. It supports identity grouping, targeted repository filters, report output and charts without requiring a hosted analytics service.
System design
Interfaces
Input
Analysis
Output
Connections
- CLI · Commander runs Stats entry point
- ESM library exports exposes Stats entry point
- Stats entry point parses commits from Git log
- Stats entry point feeds records to Analyzer + aggregator
- Analyzer + aggregator formats into Reports
- Analyzer + aggregator renders into Charts · SVG/PNG
01
Input · Git history
The stats entry point resolves a repository, translates date/branch/author/path options into Git log arguments and parses the resulting commit records.
02
Analysis · Contributor aggregation
Dedicated analyzer and aggregator modules compute contributor totals, line changes, file activity, frequency summaries and a weekday-by-hour heatmap.
03
Output · Reports and charts
Separate output, report and chart modules format results. Chart generation includes contributor commits, net lines and activity heatmaps, with SVG and PNG options.
04
Interfaces · CLI and ESM library
Commander orchestrates command-line use. Package subpath exports expose stats, charts, reports, output and workflow functions to programmatic consumers.
Decisions
- One analysis pipeline, two interfaces
- The CLI calls the stats API before producing reports or charts. ESM subpath exports let consumers compose the same capabilities in their own tooling.
- Normalize contributor identities
- Grouping by email or name, aliases and similarity handling account for contributors whose commit identities differ across time or machines.
- Make expensive work optional
- Line counting can be disabled when commit-level analysis is sufficient. This is a configurable performance tradeoff, not a claimed benchmark.
- Separate analysis from presentation
- Git parsing, analytics, reports and charts are independent modules, so output formats do not dictate the core aggregation model.
Implementation
- Repository validation and configurable branch, date, author, merge and path filtering before analysis.
- Contributor grouping, alias handling, sorting and top-N limiting, plus additions/deletions and contributor file data.
- Monthly and weekly commit frequency maps and a 7 × 24 activity heatmap.
- Console output, report generation including HTML, and contributor/activity charts using Chart.js and chartjs-node-canvas.
- Optional GitHub Actions workflow generation, module-level tests and an end-to-end test suite in the repository.
Results and learnings
The package manifest identifies version 2.2.0, MIT licensing, a CLI binary and modular ESM exports; its declared runtime is Node.js ≥20.19.5.
The implemented pipeline supports reusable contributor analytics, reports and charts. Repository test files are evidence of testing infrastructure, not a verified coverage percentage.
Single-owner file detection is implemented, but the numeric bus-factor score and candidate list remain placeholders in the analyzer. They are not claimed as calculated risk metrics.
No adoption or runtime benchmark figures were verified. A useful engineering lesson is distinguishing measured analytics from unfinished derived metrics.