@chengyixu/gitpulse 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +122 -36
  2. package/package.json +27 -16
package/README.md CHANGED
@@ -1,74 +1,160 @@
1
1
  # gitpulse
2
2
 
3
- Instant health check for any GitHub repository. Answers the question: **"Should I depend on this repo?"**
3
+ [![npm version](https://img.shields.io/npm/v/@chengyixu/gitpulse.svg)](https://www.npmjs.com/package/@chengyixu/gitpulse)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@chengyixu/gitpulse.svg)](https://www.npmjs.com/package/@chengyixu/gitpulse)
5
+ [![license](https://img.shields.io/npm/l/@chengyixu/gitpulse.svg)](https://github.com/chengyixu/gitpulse/blob/main/LICENSE)
4
6
 
5
- ## Install
7
+ > Instant health check for any GitHub repository. Answers the question: **"Should I depend on this repo?"**
8
+
9
+ One command gives you activity scores, bus factor analysis, response time estimates, and a clear verdict -- so you can make informed decisions before adding a dependency or contributing to a project.
10
+
11
+ ## Demo
6
12
 
7
- ```bash
8
- npm install -g gitpulse
9
13
  ```
14
+ $ gitpulse facebook/react
15
+
16
+ facebook/react -- Active & Healthy
17
+ ========================================================
18
+ Stars: 232,000 Forks: 47,200 Watchers: 6,700
19
+ 940 open issues
20
+ A JavaScript library for building user interfaces
10
21
 
11
- Or run directly:
22
+ ACTIVITY (last 30 days) Score: 82/100
23
+ ----------------------------------------------------------
24
+ Commits: 147 (38 in last 7d) [################....]
25
+ PRs opened: 52
26
+ PRs merged: 41
27
+ Issues opened: 28
28
+ Issues closed: 19
29
+
30
+ BUS FACTOR
31
+ ----------------------------------------------------------
32
+ Bus factor: 8 (1,842 total contributors)
33
+ Top: @acdlite (18%), @gnoff (14%), @sebmarkbage (11%)
34
+
35
+ HEALTH
36
+ ----------------------------------------------------------
37
+ First response: ~4 hours (median)
38
+ PR merge time: ~18 hours (median)
39
+ Issue close rate: 68%
40
+
41
+ VERDICT: Active & Healthy
42
+ ```
43
+
44
+ ## Install
12
45
 
13
46
  ```bash
14
- npx gitpulse facebook/react
47
+ npm install -g @chengyixu/gitpulse
15
48
  ```
16
49
 
17
- ## What it shows
50
+ Or run without installing:
18
51
 
19
- - **Activity Score** (0-100) — commits, PRs, and issues in the last 30 days
20
- - **Bus Factor** — how many contributors do 80% of the commits
21
- - **Health Metrics** — estimated first response time, PR merge time, issue close rate
22
- - **Dependencies** — count of runtime and dev dependencies
23
- - **Verdict** — one-line assessment: "Active & Healthy", "Declining", "Abandoned", etc.
52
+ ```bash
53
+ npx @chengyixu/gitpulse facebook/react
54
+ ```
24
55
 
25
56
  ## Usage
26
57
 
58
+ ### Full health report
59
+
27
60
  ```bash
28
- # Full report
29
61
  gitpulse facebook/react
62
+ ```
63
+
64
+ ### Compact one-line summary
30
65
 
31
- # Compact one-liner
66
+ ```bash
32
67
  gitpulse vercel/next.js --compact
68
+ # => next.js Active & Healthy Score: 91/100 Bus: 12 Stars: 128k
69
+ ```
33
70
 
34
- # JSON output for scripting
35
- gitpulse pallets/flask --json
71
+ ### JSON output for scripting
36
72
 
37
- # Also accepts full GitHub URLs
38
- gitpulse https://github.com/denoland/deno
73
+ ```bash
74
+ gitpulse pallets/flask --json
39
75
  ```
40
76
 
41
- ## Output example
77
+ ### Works with full GitHub URLs
42
78
 
79
+ ```bash
80
+ gitpulse https://github.com/denoland/deno
43
81
  ```
44
- 💚 facebook/react — Active & Healthy
45
- ────────────────────────────────────────────────────────
46
- ⭐ 232,000 🔴 47,200 👁 6,700 📋 940 open issues
47
- A JavaScript library for building user interfaces
48
82
 
49
- ACTIVITY (last 30 days)
50
- Score: ████████████████░░░░ 82/100
51
- Commits: 147 (38 in last 7d)
52
- PRs opened: 52
53
- PRs merged: 41
54
- ...
83
+ ## Use Cases
55
84
 
56
- BUS FACTOR
57
- Bus factor: 8 (1,842 total contributors)
58
- ...
85
+ **Evaluating a new dependency:**
86
+ ```bash
87
+ # Before adding a package, check if the repo is maintained
88
+ gitpulse expressjs/express
89
+ gitpulse fastify/fastify
90
+ # Compare verdicts and pick the healthier project
91
+ ```
59
92
 
60
- VERDICT: 💚 Active & Healthy
93
+ **Auditing your stack:**
94
+ ```bash
95
+ # Check health of repos you depend on
96
+ for repo in facebook/react vercel/next.js prisma/prisma; do
97
+ gitpulse $repo --compact
98
+ done
61
99
  ```
62
100
 
63
- ## Higher rate limits
101
+ **CI/CD health gates:**
102
+ ```bash
103
+ # Use JSON output in scripts
104
+ SCORE=$(gitpulse some/repo --json | jq '.activity.activityScore')
105
+ if [ "$SCORE" -lt 20 ]; then
106
+ echo "WARNING: dependency repo has low activity"
107
+ fi
108
+ ```
64
109
 
65
- By default, GitHub allows 60 API requests per hour for unauthenticated users. For higher limits (5,000/hr), set a token:
110
+ ## What it measures
111
+
112
+ | Metric | Description |
113
+ |--------|-------------|
114
+ | **Activity Score** (0-100) | Weighted score of commits, PRs, and issues in the last 30 days |
115
+ | **Bus Factor** | How many contributors produce 80% of commits |
116
+ | **First Response Time** | Median time to first comment on issues |
117
+ | **PR Merge Time** | Median time from PR open to merge |
118
+ | **Issue Close Rate** | Percentage of issues that get closed |
119
+ | **Verdict** | One-line assessment: Active & Healthy, Declining, Abandoned, etc. |
120
+
121
+ ### Verdict Levels
122
+
123
+ | Verdict | Meaning |
124
+ |---------|---------|
125
+ | Active & Healthy | High activity, multiple contributors, responsive |
126
+ | Active but Understaffed | Lots of activity, low bus factor |
127
+ | Slowing Down | Decreasing activity trend |
128
+ | Minimal Maintenance | Some activity, mostly patches |
129
+ | Declining | Significant drop in activity |
130
+ | Abandoned | No meaningful activity in 30+ days |
131
+ | Archived | Repository is archived on GitHub |
132
+
133
+ ## Why gitpulse over alternatives?
134
+
135
+ | Feature | gitpulse | GitHub Insights | OSSF Scorecard | Snyk Advisor |
136
+ |---------|:--------:|:---------------:|:--------------:|:------------:|
137
+ | CLI-first | Yes | No (web only) | Yes | No |
138
+ | Bus factor analysis | Yes | No | No | No |
139
+ | Activity scoring | Yes | Partial | Partial | Yes |
140
+ | Response time estimates | Yes | No | No | Partial |
141
+ | One-command verdict | Yes | No | No | No |
142
+ | JSON output | Yes | No | Yes | No |
143
+ | Works without auth | Yes | Requires login | Yes | Yes |
144
+ | Zero config | Yes | N/A | Needs setup | N/A |
145
+
146
+ ## Authentication
147
+
148
+ By default, GitHub allows 60 API requests/hour for unauthenticated users. For higher limits (5,000/hr), set a token:
66
149
 
67
150
  ```bash
68
151
  export GITHUB_TOKEN=ghp_your_token_here
69
- gitpulse facebook/react
152
+ # or
153
+ export GH_TOKEN=ghp_your_token_here
70
154
  ```
71
155
 
156
+ No special scopes are needed -- a basic token with no permissions works fine.
157
+
72
158
  ## License
73
159
 
74
160
  MIT
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@chengyixu/gitpulse",
3
- "version": "1.0.0",
4
- "description": "Instant health check for any GitHub repo. Activity score, bus factor, response times, dependency freshness, and a one-line verdict.",
3
+ "version": "1.0.1",
4
+ "description": "Instant health check for any GitHub repository -- activity score, bus factor, response times, and a one-line verdict to evaluate open source project health",
5
5
  "main": "dist/index.js",
6
6
  "bin": {
7
7
  "gitpulse": "dist/index.js"
@@ -13,20 +13,35 @@
13
13
  },
14
14
  "keywords": [
15
15
  "github",
16
- "repo",
17
- "health",
18
- "activity",
16
+ "repository-health",
19
17
  "bus-factor",
20
- "dependencies",
21
- "cli",
22
- "analysis",
18
+ "activity-score",
23
19
  "open-source",
24
- "maintenance",
25
- "pulse",
26
- "metrics"
20
+ "dependency-evaluation",
21
+ "repo-analysis",
22
+ "github-metrics",
23
+ "project-health",
24
+ "maintenance-score",
25
+ "contributor-analysis",
26
+ "cli",
27
+ "github-api",
28
+ "code-quality",
29
+ "devtools",
30
+ "oss-health"
27
31
  ],
28
- "author": "wilsonxu",
32
+ "author": "Chengyi Xu <chengyixu@outlook.com>",
29
33
  "license": "MIT",
34
+ "repository": {
35
+ "type": "git",
36
+ "url": "git+https://github.com/chengyixu/gitpulse.git"
37
+ },
38
+ "homepage": "https://github.com/chengyixu/gitpulse#readme",
39
+ "bugs": {
40
+ "url": "https://github.com/chengyixu/gitpulse/issues"
41
+ },
42
+ "publishConfig": {
43
+ "access": "public"
44
+ },
30
45
  "dependencies": {
31
46
  "chalk": "^4.1.2",
32
47
  "commander": "^12.1.0",
@@ -41,9 +56,5 @@
41
56
  ],
42
57
  "engines": {
43
58
  "node": ">=18.0.0"
44
- },
45
- "repository": {
46
- "type": "git",
47
- "url": "https://github.com/chengyixu/gitpulse"
48
59
  }
49
60
  }