gitfamiliar 0.4.0 → 0.7.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
 

package/dist/bin/gitfamiliar.js

@@ -1,16 +1,14 @@
 #!/usr/bin/env node
 import {
   GitClient,
-  GitHubClient,
   buildFileTree,
   computeFamiliarity,
   createFilter,
   parseExpirationConfig,
   processBatch,
-  resolveGitHubToken,
   resolveUser,
   walkFiles
-} from "../chunk-V27FX6R6.js";
+} from "../chunk-BQCHOSLA.js";
 
 // src/cli/index.ts
 import { Command } from "commander";
@@ -18,8 +16,7 @@ import { Command } from "commander";
 // src/core/types.ts
 var DEFAULT_WEIGHTS = {
   blame: 0.5,
-  commit: 0.35,
-  review: 0.15
+  commit: 0.5
 };
 var DEFAULT_EXPIRATION = {
   policy: "never"
@@ -28,7 +25,6 @@ var DEFAULT_EXPIRATION = {
 // src/cli/options.ts
 function parseOptions(raw, repoPath) {
   const mode = validateMode(raw.mode || "binary");
-  const filter = validateFilter(raw.filter || "all");
   let weights = DEFAULT_WEIGHTS;
   if (raw.weights) {
     weights = parseWeights(raw.weights);
@@ -52,7 +48,6 @@ function parseOptions(raw, repoPath) {
   return {
     mode,
     user,
-    filter,
     expiration,
     html: raw.html || false,
     weights,
@@ -60,18 +55,11 @@ function parseOptions(raw, repoPath) {
     team: raw.team || false,
     teamCoverage: raw.teamCoverage || false,
     hotspot,
-    window: windowDays,
-    githubUrl: raw.githubUrl,
-    checkGithub: raw.checkGithub || false
+    window: windowDays
   };
 }
 function validateMode(mode) {
-  const valid = [
-    "binary",
-    "authorship",
-    "review-coverage",
-    "weighted"
-  ];
+  const valid = ["binary", "authorship", "weighted"];
   if (!valid.includes(mode)) {
     throw new Error(
       `Invalid mode: "${mode}". Valid modes: ${valid.join(", ")}`
@@ -79,27 +67,16 @@ function validateMode(mode) {
   }
   return mode;
 }
-function validateFilter(filter) {
-  const valid = ["all", "written", "reviewed"];
-  if (!valid.includes(filter)) {
-    throw new Error(
-      `Invalid filter: "${filter}". Valid filters: ${valid.join(", ")}`
-    );
-  }
-  return filter;
-}
 function parseWeights(s) {
   const parts = s.split(",").map(Number);
-  if (parts.length !== 3 || parts.some(isNaN)) {
-    throw new Error(
-      `Invalid weights: "${s}". Expected format: "0.5,0.35,0.15"`
-    );
+  if (parts.length !== 2 || parts.some(isNaN)) {
+    throw new Error(`Invalid weights: "${s}". Expected format: "0.5,0.5"`);
   }
-  const sum = parts[0] + parts[1] + parts[2];
+  const sum = parts[0] + parts[1];
   if (Math.abs(sum - 1) > 0.01) {
     throw new Error(`Weights must sum to 1.0, got ${sum}`);
   }
-  return { blame: parts[0], commit: parts[1], review: parts[2] };
+  return { blame: parts[0], commit: parts[1] };
 }
 
 // src/cli/output/terminal.ts
@@ -125,8 +102,6 @@ function getModeLabel(mode) {
       return "Binary mode";
     case "authorship":
       return "Authorship mode";
-    case "review-coverage":
-      return "Review Coverage mode";
     case "weighted":
       return "Weighted mode";
     default:
@@ -166,7 +141,9 @@ function renderFolder(node, indent, mode, maxDepth) {
 function renderTerminal(result) {
   const { tree, repoName, mode } = result;
   console.log("");
-  console.log(chalk.bold(`GitFamiliar \u2014 ${repoName} (${getModeLabel(mode)})`));
+  console.log(
+    chalk.bold(`GitFamiliar \u2014 ${repoName} (${getModeLabel(mode)})`)
+  );
   console.log("");
   if (mode === "binary") {
     const readCount = tree.readCount || 0;
@@ -183,10 +160,8 @@ function renderTerminal(result) {
   }
   console.log("");
   if (mode === "binary") {
-    const { writtenCount, reviewedCount, bothCount } = result;
-    console.log(
-      `Written: ${writtenCount} files | Reviewed: ${reviewedCount} files | Both: ${bothCount} files`
-    );
+    const { writtenCount } = result;
+    console.log(`Written: ${writtenCount} files`);
     console.log("");
   }
 }
@@ -244,28 +219,7 @@ function generateTreemapHTML(result) {
   #breadcrumb span { cursor: pointer; color: #5eadf7; }
   #breadcrumb span:hover { text-decoration: underline; }
   #breadcrumb .sep { color: #666; margin: 0 4px; }
-  #controls {
-    padding: 8px 24px;
-    background: #16213e;
-    border-bottom: 1px solid #0f3460;
-    display: flex;
-    gap: 12px;
-    align-items: center;
-  }
-  #controls button {
-    padding: 4px 12px;
-    border: 1px solid #0f3460;
-    background: #1a1a2e;
-    color: #e0e0e0;
-    border-radius: 4px;
-    cursor: pointer;
-    font-size: 12px;
-  }
-  #controls button.active {
-    background: #e94560;
-    border-color: #e94560;
-    color: white;
-  }
+
   #treemap { width: 100%; }
   #tooltip {
     position: absolute;
@@ -306,13 +260,7 @@ function generateTreemapHTML(result) {
   <div class="info">${mode.charAt(0).toUpperCase() + mode.slice(1)} mode | ${result.totalFiles} files</div>
 </div>
 <div id="breadcrumb"><span onclick="zoomTo('')">root</span></div>
-${mode === "binary" ? `
-<div id="controls">
-  <span style="font-size:12px;color:#888;">Filter:</span>
-  <button class="active" onclick="setFilter('all')">All</button>
-  <button onclick="setFilter('written')">Written only</button>
-  <button onclick="setFilter('reviewed')">Reviewed only</button>
-</div>` : ""}
+
 <div id="treemap"></div>
 <div id="tooltip"></div>
 <div id="legend">
@@ -325,7 +273,6 @@ ${mode === "binary" ? `
 <script>
 const rawData = ${dataJson};
 const mode = "${mode}";
-let currentFilter = 'all';
 let currentPath = '';
 
 function scoreColor(score) {
@@ -340,9 +287,6 @@ function scoreColor(score) {
 }
 
 function getNodeScore(node) {
-  if (mode !== 'binary') return node.score;
-  if (currentFilter === 'written') return node.isWritten ? 1 : 0;
-  if (currentFilter === 'reviewed') return node.isReviewed ? 1 : 0;
   return node.score;
 }
 
@@ -382,10 +326,8 @@ function render() {
 
   const headerH = document.getElementById('header').offsetHeight;
   const breadcrumbH = document.getElementById('breadcrumb').offsetHeight;
-  const controlsEl = document.getElementById('controls');
-  const controlsH = controlsEl ? controlsEl.offsetHeight : 0;
   const width = window.innerWidth;
-  const height = window.innerHeight - headerH - breadcrumbH - controlsH;
+  const height = window.innerHeight - headerH - breadcrumbH;
 
   const targetNode = currentPath ? findNode(rawData, currentPath) : rawData;
   if (!targetNode) return;
@@ -492,9 +434,7 @@ function showTooltip(data, event) {
   if (data.commitScore !== undefined) {
     html += '<br>Commit: ' + Math.round(data.commitScore * 100) + '%';
   }
-  if (data.reviewScore !== undefined) {
-    html += '<br>Review: ' + Math.round(data.reviewScore * 100) + '%';
-  }
+
   if (data.isExpired) {
     html += '<br><span style="color:#e94560">Expired</span>';
   }
@@ -523,14 +463,6 @@ function updateBreadcrumb() {
   el.innerHTML = html;
 }
 
-function setFilter(f) {
-  currentFilter = f;
-  document.querySelectorAll('#controls button').forEach(btn => {
-    btn.classList.toggle('active', btn.textContent.toLowerCase().includes(f));
-  });
-  render();
-}
-
 window.addEventListener('resize', render);
 render();
 </script>
@@ -1162,7 +1094,6 @@ async function computeMultiUser(options) {
   const userSummaries = results.map((r) => ({
     user: { name: r.result.userName, email: "" },
     writtenCount: r.result.writtenCount,
-    reviewedCount: r.result.reviewedCount,
     overallScore: r.result.tree.score
   }));
   return {
@@ -1199,8 +1130,7 @@ function mergeResults(results) {
       scores.push({
         user: { name: userName, email: "" },
         score: file.score,
-        isWritten: file.isWritten,
-        isReviewed: file.isReviewed
+        isWritten: file.isWritten
       });
     });
   }
@@ -1275,8 +1205,6 @@ function getModeLabel2(mode) {
       return "Binary mode";
     case "authorship":
       return "Authorship mode";
-    case "review-coverage":
-      return "Review Coverage mode";
     case "weighted":
       return "Weighted mode";
     default:
@@ -1323,7 +1251,7 @@ function renderMultiUserTerminal(result) {
     const pct = formatPercent2(summary.overallScore);
     if (mode === "binary") {
       console.log(
-        `  ${name} ${bar}  ${pct.padStart(4)} (${summary.writtenCount + summary.reviewedCount}/${totalFiles} files)`
+        `  ${name} ${bar}  ${pct.padStart(4)} (${summary.writtenCount}/${totalFiles} files)`
       );
     } else {
       console.log(`  ${name} ${bar}  ${pct.padStart(4)}`);
@@ -1332,9 +1260,7 @@ function renderMultiUserTerminal(result) {
   console.log("");
   const nameWidth = 20;
   const headerNames = userSummaries.map((s) => truncateName(s.user.name, 7).padStart(7)).join("  ");
-  console.log(
-    chalk3.bold("Folders:") + " ".repeat(nameWidth - 4) + headerNames
-  );
+  console.log(chalk3.bold("Folders:") + " ".repeat(nameWidth - 4) + headerNames);
   const folderLines = renderFolder3(tree, 1, 2, nameWidth);
   for (const line of folderLines) {
     console.log(line);
@@ -2149,58 +2075,6 @@ async function generateAndOpenHotspotHTML(result, repoPath) {
   await openBrowser(outputPath);
 }
 
-// src/github/check.ts
-async function checkGitHubConnection(repoPath, githubUrl) {
-  const gitClient = new GitClient(repoPath);
-  if (!await gitClient.isRepo()) {
-    console.error("Error: Not a git repository.");
-    process.exit(1);
-  }
-  const remoteUrl = await gitClient.getRemoteUrl();
-  if (!remoteUrl) {
-    console.error("Error: No git remote found.");
-    process.exit(1);
-  }
-  console.log(`Remote URL:   ${remoteUrl}`);
-  const parsed = GitHubClient.parseRemoteUrl(remoteUrl, githubUrl);
-  if (!parsed) {
-    console.error("Error: Could not parse remote URL as a GitHub repository.");
-    process.exit(1);
-  }
-  console.log(`Hostname:     ${parsed.hostname}`);
-  console.log(`Repository:   ${parsed.owner}/${parsed.repo}`);
-  console.log(`API Base URL: ${parsed.apiBaseUrl}`);
-  console.log(`
-Resolving token for hostname: ${parsed.hostname}`);
-  const token = resolveGitHubToken(parsed.hostname);
-  if (!token) {
-    console.error(
-      `No GitHub token found.
-Tried:
-  1. Environment variables: GITHUB_TOKEN, GH_TOKEN
-  2. gh auth token --hostname ${parsed.hostname}
-` + (parsed.hostname !== "github.com" ? `  3. gh auth token (default host fallback)
-` : "") + `
-Please run: gh auth login` + (parsed.hostname !== "github.com" ? ` --hostname ${parsed.hostname}` : "")
-    );
-    process.exit(1);
-  }
-  console.log(`Token:        ****${token.slice(-4)}`);
-  console.log("\nVerifying API connectivity...");
-  try {
-    const client = new GitHubClient(token, parsed.apiBaseUrl);
-    const user = await client.verifyConnection();
-    console.log(
-      `Authenticated as: ${user.login}${user.name ? ` (${user.name})` : ""}`
-    );
-    console.log("\nGitHub connection OK.");
-  } catch (error) {
-    console.error(`
-API connection failed: ${error.message}`);
-    process.exit(1);
-  }
-}
-
 // src/cli/index.ts
 function collect(value, previous) {
   return previous.concat([value]);
@@ -2209,24 +2083,20 @@ function createProgram() {
   const program2 = new Command();
   program2.name("gitfamiliar").description("Visualize your code familiarity from Git history").version("0.1.1").option(
     "-m, --mode <mode>",
-    "Scoring mode: binary, authorship, review-coverage, weighted",
+    "Scoring mode: binary, authorship, weighted",
     "binary"
   ).option(
     "-u, --user <user>",
     "Git user name or email (repeatable for comparison)",
     collect,
     []
-  ).option(
-    "-f, --filter <filter>",
-    "Filter mode: all, written, reviewed",
-    "all"
   ).option(
     "-e, --expiration <policy>",
     "Expiration policy: never, time:180d, change:50%, combined:365d:50%",
     "never"
   ).option("--html", "Generate HTML treemap report", false).option(
     "-w, --weights <weights>",
-    'Weights for weighted mode: blame,commit,review (e.g., "0.5,0.35,0.15")'
+    'Weights for weighted mode: blame,commit (e.g., "0.5,0.5")'
   ).option("--team", "Compare all contributors", false).option(
     "--team-coverage",
     "Show team coverage map (bus factor analysis)",
@@ -2234,21 +2104,10 @@ function createProgram() {
   ).option("--hotspot [mode]", "Hotspot analysis: personal (default) or team").option(
     "--window <days>",
     "Time window for hotspot analysis in days (default: 90)"
-  ).option(
-    "--github-url <hostname>",
-    "GitHub Enterprise hostname (e.g. ghe.example.com). Auto-detected from git remote if omitted."
-  ).option(
-    "--check-github",
-    "Verify GitHub API connectivity and show connection info",
-    false
   ).action(async (rawOptions) => {
     try {
       const repoPath = process.cwd();
       const options = parseOptions(rawOptions, repoPath);
-      if (options.checkGithub) {
-        await checkGitHubConnection(repoPath, options.githubUrl);
-        return;
-      }
       if (options.hotspot) {
         const result2 = await computeHotspots(options);
         if (options.html) {