gitfamiliar 0.5.0 → 0.8.0

package/README.md

@@ -7,7 +7,6 @@
     <a href="https://www.npmjs.com/package/gitfamiliar"><img src="https://img.shields.io/npm/v/gitfamiliar.svg" alt="npm version"></a>
     <a href="https://www.npmjs.com/package/gitfamiliar"><img src="https://img.shields.io/npm/dm/gitfamiliar.svg" alt="npm downloads"></a>
     <a href="https://github.com/kuze/gitfamiliar/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/gitfamiliar.svg" alt="license"></a>
-    <a href="https://github.com/kuze/gitfamiliar/actions"><img src="https://github.com/kuze/gitfamiliar/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
   </p>
 </p>
 
@@ -35,7 +34,7 @@ Overall: 58/172 files (34%)
   tests/        ░░░░░░░░░░   0% (0/14 files)
   config/       ██████░░░░  60% (3/5 files)
 
-Written: 42 files | Reviewed: 23 files | Both: 7 files
+Written: 42 files
 ```
 
 Use `--html` to generate an interactive treemap in the browser:
@@ -45,7 +44,7 @@ $ npx gitfamiliar --html
 ```
 
 > Area = lines of code, Color = familiarity (red -> green).
-> Click folders to drill down. Toggle between All / Written / Reviewed views.
+> Click folders to drill down.
 
 ## Quick Start
 
@@ -68,31 +67,21 @@ npm install -g gitfamiliar
 | What it measures | How much you **wrote** | How well you **understand** |
 | Metric | Lines / commits (cumulative) | Familiarity score (multi-signal) |
 | Use case | Contribution stats | Onboarding progress |
-| Review awareness | No | Yes (PR reviews count) |
 | Time decay | No | Yes (knowledge fades) |
+| Team analysis | No | Yes (bus factor, multi-user comparison) |
 
 ## Scoring Modes
 
-GitFamiliar provides 4 modes so you can choose the right lens for your situation.
-
 ### Binary (default)
 
-Files are "read" or "unread". A file counts as read if you committed to it or approved a PR containing it.
+Files are "written" or "not written". A file counts as written if you have at least one commit touching it.
 
 ```
-familiarity = read_files / total_files
+familiarity = written_files / total_files
 ```
 
-| View | Shows |
-|---|---|
-| All (default) | Written + Reviewed files |
-| Written only | Only files you committed to |
-| Reviewed only | Only files you reviewed via PR |
-
 ```bash
-gitfamiliar                    # All
-gitfamiliar --filter written   # Written only
-gitfamiliar --filter reviewed  # Reviewed only
+gitfamiliar                    # default
 ```
 
 > Best for: **New team members** tracking onboarding progress.
@@ -112,41 +101,24 @@ gitfamiliar --mode authorship
 ```
 
 > Best for: **Tech leads** assessing bus factor and code ownership.
-> A file where one person owns 95% of the lines is a risk signal.
-
-### Review Coverage
-
-Files you reviewed through PR approvals or comments, excluding your own commits.
-
-```
-score = reviewed_files / total_files
-```
-
-```bash
-gitfamiliar --mode review-coverage
-```
-
-> Best for: **Senior engineers** tracking how broadly they review.
-> Requires a GitHub token (see [GitHub Integration](#github-integration)).
 
 ### Weighted
 
-The most nuanced mode. Combines three signals with configurable weights and time decay:
+Combines two signals with configurable weights and time decay:
 
 ```
-familiarity = w1 x blame_score + w2 x commit_score + w3 x review_score
+familiarity = w1 x blame_score + w2 x commit_score
 ```
 
-Default weights: `blame=0.5, commit=0.35, review=0.15`
+Default weights: `blame=0.5, commit=0.5`
 
 Key features:
 - **Sigmoid normalization** prevents a single large commit from dominating
 - **Recency decay** (half-life: 180 days) models knowledge fading over time
-- **Scope factor** discounts reviews on huge PRs (attention dilution)
 
 ```bash
 gitfamiliar --mode weighted
-gitfamiliar --mode weighted --weights "0.6,0.3,0.1"   # custom weights
+gitfamiliar --mode weighted --weights "0.6,0.4"   # custom weights
 ```
 
 <details>
@@ -162,31 +134,65 @@ commit_score:
   commit 2 (45 days ago,  +5/-2): sigmoid(6/200)  x decay(45d) = 0.09 x 0.84
   total: min(1, 0.39) = 0.39
 
-review_score:
-  PR approved (20 days ago, 4 files): 0.30 x 1.0 x decay(20d) = 0.28
-
-familiarity  = 0.5 x 0.15 + 0.35 x 0.39 + 0.15 x 0.28
-             = 0.075 + 0.137 + 0.042
-             = 0.254 -> 25%
+familiarity  = 0.5 x 0.15 + 0.5 x 0.39
+             = 0.075 + 0.195
+             = 0.27 -> 27%
 ```
 
 </details>
 
 > Best for: **Power users** who want the most accurate picture.
-> Score breakdowns are always visible so it never feels like a black box.
+
+## Team Features
+
+### Multi-User Comparison
+
+Compare familiarity across multiple team members:
+
+```bash
+gitfamiliar --user "Alice" --user "Bob"   # specific users
+gitfamiliar --team                         # all contributors
+```
+
+### Team Coverage Map
+
+Visualize bus factor — how many people know each part of the codebase:
+
+```bash
+gitfamiliar --team-coverage
+gitfamiliar --team-coverage --html
+```
+
+Shows risk levels per folder:
+- **RISK** (0-1 contributors) — single point of failure
+- **MODERATE** (2-3 contributors) — some coverage
+- **SAFE** (4+ contributors) — well-distributed knowledge
+
+### Hotspot Analysis
+
+Find files that are frequently changed but poorly understood:
+
+```bash
+gitfamiliar --hotspot                      # personal hotspots
+gitfamiliar --hotspot team                 # team hotspots
+gitfamiliar --hotspot --window 30          # last 30 days only
+gitfamiliar --hotspot --html               # scatter plot visualization
+```
+
+Risk = high change frequency x low familiarity.
 
 ## Expiration Policies
 
-By default, "read" status never expires. But real knowledge fades. Configure expiration to keep scores honest:
+By default, "written" status never expires. But real knowledge fades. Configure expiration to keep scores honest:
 
 | Policy | Flag | What happens |
 |---|---|---|
-| Never | `--expiration never` | Once read, always read (default) |
+| Never | `--expiration never` | Once written, always counted (default) |
 | Time-based | `--expiration time:180d` | Expires 180 days after your last touch |
 | Change-based | `--expiration change:50%` | Expires if 50%+ of the file changed since you last touched it |
 | Combined | `--expiration combined:365d:50%` | Expires if **either** condition is met |
 
-The change-based policy is the smartest: it detects when the code you read has been substantially rewritten, meaning your understanding is likely outdated.
+The change-based policy is the smartest: it detects when the code you wrote has been substantially rewritten, meaning your understanding is likely outdated.
 
 ## File Filtering
 
@@ -210,20 +216,6 @@ third_party/
 **/migrations/
 ```
 
-## GitHub Integration
-
-For review-related features (Review Coverage mode, reviewed files in Binary mode), GitFamiliar needs a GitHub token:
-
-```bash
-# Option 1: environment variable
-export GITHUB_TOKEN=ghp_xxxxxxxxxxxxx
-
-# Option 2: GitHub CLI (auto-detected if installed)
-gh auth login
-```
-
-Without a token, GitFamiliar works perfectly for all non-review features. Review features degrade gracefully with a helpful message.
-
 ## CLI Reference
 
 ```
@@ -231,15 +223,18 @@ Usage: gitfamiliar [options]
 
 Options:
   -m, --mode <mode>          Scoring mode (default: "binary")
-                             Choices: binary, authorship, review-coverage, weighted
-  -u, --user <user>          Git user name or email (default: git config)
-  -f, --filter <filter>      Display filter (default: "all")
-                             Choices: all, written, reviewed
+                             Choices: binary, authorship, weighted
+  -u, --user <user>          Git user name or email (repeatable for comparison)
+                             Default: git config user.name
   -e, --expiration <policy>  Expiration policy (default: "never")
                              Examples: time:180d, change:50%, combined:365d:50%
       --html                 Generate interactive HTML treemap report
-  -w, --weights <weights>    Weights for weighted mode: blame,commit,review
-                             Example: "0.5,0.35,0.15" (must sum to 1.0)
+  -w, --weights <weights>    Weights for weighted mode: blame,commit
+                             Example: "0.6,0.4" (must sum to 1.0)
+      --team                 Compare all contributors
+      --team-coverage         Show team coverage map (bus factor analysis)
+      --hotspot [mode]       Hotspot analysis: personal (default) or team
+      --window <days>        Time window for hotspot analysis (default: 90)
   -V, --version              Output version number
   -h, --help                 Display help
 ```
@@ -253,9 +248,8 @@ import { computeFamiliarity } from 'gitfamiliar';
 
 const result = await computeFamiliarity({
   mode: 'binary',
-  filter: 'all',
   expiration: { policy: 'never' },
-  weights: { blame: 0.5, commit: 0.35, review: 0.15 },
+  weights: { blame: 0.5, commit: 0.5 },
   html: false,
   repoPath: '/path/to/repo',
 });
@@ -267,7 +261,6 @@ console.log(`Score: ${Math.round(result.tree.score * 100)}%`);
 
 - **Node.js** >= 18
 - **Git** (available in PATH)
-- **GitHub token** (optional, for review features)
 
 ## Contributing
 
@@ -284,8 +277,6 @@ npm test
 ## Roadmap
 
 - [ ] **Dependency Awareness** - Factor in understanding of imported files
-- [ ] **Churn Risk Alert** - Highlight files with high change frequency + low familiarity
-- [ ] **GitHub Action** - Post familiarity reports as PR comments
 - [ ] **VS Code Extension** - See familiarity scores inline in the editor
 - [ ] **README Badge** - Codecov-style badge for your project README