gitfamiliar 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GitFamiliar Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# GitFamiliar
+
+**Visualize your code familiarity from Git history.**
+
+Existing tools (git-fame, GitHub Contributors, etc.) measure _how much_ you've written. GitFamiliar estimates _how well_ you understand the codebase. Built for engineers joining a new project, it lets you and your team objectively track onboarding progress.
+
+```
+GitFamiliar — my-project (Binary mode)
+
+Overall: 58/172 files (34%)
+
+  src/
+    auth/       ████████░░  80% (4/5 files)
+    api/        ███░░░░░░░  30% (6/20 files)
+    components/ █░░░░░░░░░  12% (3/25 files)
+    utils/      ██████████ 100% (8/8 files)
+  tests/        ░░░░░░░░░░   0% (0/14 files)
+  config/       ██████░░░░  60% (3/5 files)
+
+Written: 42 files | Reviewed: 23 files | Both: 7 files
+```
+
+## Install
+
+```bash
+npx gitfamiliar
+```
+
+Or install globally:
+
+```bash
+npm install -g gitfamiliar
+```
+
+## Usage
+
+Run inside any Git repository:
+
+```bash
+# Binary mode (default) — which files have you touched?
+gitfamiliar
+
+# Authorship mode — how much of the current code did you write? (git blame)
+gitfamiliar --mode authorship
+
+# Review Coverage — which files have you reviewed via PR?
+gitfamiliar --mode review-coverage
+
+# Weighted mode — combined score from blame, commits, and reviews
+gitfamiliar --mode weighted
+
+# HTML treemap report (opens in browser)
+gitfamiliar --html
+
+# Check a specific user
+gitfamiliar --user kota
+
+# Filter by how you touched the code
+gitfamiliar --filter written    # only files you committed to
+gitfamiliar --filter reviewed   # only files you reviewed
+
+# Expiration policies
+gitfamiliar --expiration time:180d        # expire after 180 days
+gitfamiliar --expiration change:50%       # expire if 50%+ changed
+gitfamiliar --expiration combined:365d:50%
+
+# Custom weights for weighted mode
+gitfamiliar --mode weighted --weights "0.5,0.35,0.15"
+```
+
+## Scoring Modes
+
+### Binary (default)
+
+Files are either "read" or "unread". A file counts as read if you've committed to it or approved a PR containing it.
+
+```
+score = read files / total files
+```
+
+Best for: **New team members** tracking onboarding progress.
+
+### Authorship
+
+Your share of the current codebase, based on `git blame`.
+
+```
+score = your blame lines / total lines
+```
+
+Best for: **Tech leads** assessing bus factor and code ownership distribution.
+
+### Review Coverage
+
+Files you've reviewed through PR approvals or comments (excluding your own commits).
+
+```
+score = reviewed files / total files
+```
+
+Best for: **Senior engineers** tracking review breadth. Requires a GitHub token.
+
+### Weighted
+
+Combines blame, commit frequency, and review signals with configurable weights and time decay.
+
+```
+score = 0.5 × blame_score + 0.35 × commit_score + 0.15 × review_score
+```
+
+Commit contributions use sigmoid normalization and exponential recency decay (half-life: 180 days). Review scores account for PR size (attention dilution).
+
+Best for: **Power users** who want the most nuanced picture.
+
+## HTML Report
+
+Use `--html` to generate an interactive treemap visualization:
+
+- **Area** = lines of code (file/folder volume)
+- **Color** = familiarity score (red → yellow → green)
+- Click folders to drill down
+- Toggle between All / Written / Reviewed views
+- Hover for detailed scores
+
+## File Filtering
+
+GitFamiliar ignores lock files, build outputs, and generated code by default. Customize by creating `.gitfamiliarignore` in your repo root (same syntax as `.gitignore`):
+
+```gitignore
+# Example: also ignore vendor code
+vendor/
+third_party/
+```
+
+Default exclusions: `package-lock.json`, `yarn.lock`, `*.min.js`, `*.map`, `dist/`, `build/`, etc.
+
+## Expiration Policies
+
+Control whether "read" status expires over time:
+
+| Policy | Flag | Behavior |
+|---|---|---|
+| Never (default) | `--expiration never` | Once read, always read |
+| Time-based | `--expiration time:180d` | Expires 180 days after last touch |
+| Change-based | `--expiration change:50%` | Expires if 50%+ of the file changed since your last touch |
+| Combined | `--expiration combined:365d:50%` | Expires if either condition is met |
+
+## GitHub Integration
+
+For review-related features (Review Coverage mode, reviewed files in Binary mode), set a GitHub token:
+
+```bash
+# Option 1: environment variable
+export GITHUB_TOKEN=ghp_xxx
+
+# Option 2: GitHub CLI (auto-detected)
+gh auth login
+```
+
+## Requirements
+
+- Node.js >= 18
+- Git
+- GitHub token (optional, for review features)
+
+## License
+
+MIT

package/dist/bin/gitfamiliar.js

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+import {
+  computeFamiliarity,
+  parseExpirationConfig
+} from "../chunk-DW2PHZVZ.js";
+
+// src/cli/index.ts
+import { Command } from "commander";
+
+// src/core/types.ts
+var DEFAULT_WEIGHTS = {
+  blame: 0.5,
+  commit: 0.35,
+  review: 0.15
+};
+var DEFAULT_EXPIRATION = {
+  policy: "never"
+};
+
+// 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);
+  }
+  const expiration = raw.expiration ? parseExpirationConfig(raw.expiration) : DEFAULT_EXPIRATION;
+  return {
+    mode,
+    user: raw.user,
+    filter,
+    expiration,
+    html: raw.html || false,
+    weights,
+    repoPath
+  };
+}
+function validateMode(mode) {
+  const valid = ["binary", "authorship", "review-coverage", "weighted"];
+  if (!valid.includes(mode)) {
+    throw new Error(`Invalid mode: "${mode}". Valid modes: ${valid.join(", ")}`);
+  }
+  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"`);
+  }
+  const sum = parts[0] + parts[1] + parts[2];
+  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] };
+}
+
+// src/cli/output/terminal.ts
+import chalk from "chalk";
+var BAR_WIDTH = 10;
+var FILLED_CHAR = "\u2588";
+var EMPTY_CHAR = "\u2591";
+function makeBar(score) {
+  const filled = Math.round(score * BAR_WIDTH);
+  const empty = BAR_WIDTH - filled;
+  const bar = FILLED_CHAR.repeat(filled) + EMPTY_CHAR.repeat(empty);
+  if (score >= 0.8) return chalk.green(bar);
+  if (score >= 0.5) return chalk.yellow(bar);
+  if (score > 0) return chalk.red(bar);
+  return chalk.gray(bar);
+}
+function formatPercent(score) {
+  return `${Math.round(score * 100)}%`;
+}
+function getModeLabel(mode) {
+  switch (mode) {
+    case "binary":
+      return "Binary mode";
+    case "authorship":
+      return "Authorship mode";
+    case "review-coverage":
+      return "Review Coverage mode";
+    case "weighted":
+      return "Weighted mode";
+    default:
+      return mode;
+  }
+}
+function renderFolder(node, indent, mode, maxDepth) {
+  const lines = [];
+  const prefix = "  ".repeat(indent);
+  const sorted = [...node.children].sort((a, b) => {
+    if (a.type !== b.type) return a.type === "folder" ? -1 : 1;
+    return a.path.localeCompare(b.path);
+  });
+  for (const child of sorted) {
+    if (child.type === "folder") {
+      const folder = child;
+      const name = folder.path.split("/").pop() + "/";
+      const bar = makeBar(folder.score);
+      const pct = formatPercent(folder.score);
+      if (mode === "binary") {
+        const readCount = folder.readCount || 0;
+        lines.push(
+          `${prefix}${chalk.bold(name.padEnd(16))} ${bar}  ${pct.padStart(4)} (${readCount}/${folder.fileCount} files)`
+        );
+      } else {
+        lines.push(
+          `${prefix}${chalk.bold(name.padEnd(16))} ${bar}  ${pct.padStart(4)}`
+        );
+      }
+      if (indent < maxDepth) {
+        lines.push(...renderFolder(folder, indent + 1, mode, maxDepth));
+      }
+    }
+  }
+  return lines;
+}
+function renderTerminal(result) {
+  const { tree, repoName, mode } = result;
+  console.log("");
+  console.log(chalk.bold(`GitFamiliar \u2014 ${repoName} (${getModeLabel(mode)})`));
+  console.log("");
+  if (mode === "binary") {
+    const readCount = tree.readCount || 0;
+    const pct = formatPercent(tree.score);
+    console.log(`Overall: ${readCount}/${tree.fileCount} files (${pct})`);
+  } else {
+    const pct = formatPercent(tree.score);
+    console.log(`Overall: ${pct}`);
+  }
+  console.log("");
+  const folderLines = renderFolder(tree, 1, mode, 2);
+  for (const line of folderLines) {
+    console.log(line);
+  }
+  console.log("");
+  if (mode === "binary") {
+    const { writtenCount, reviewedCount, bothCount } = result;
+    console.log(
+      `Written: ${writtenCount} files | Reviewed: ${reviewedCount} files | Both: ${bothCount} files`
+    );
+    console.log("");
+  }
+}
+
+// src/cli/output/html.ts
+import { writeFileSync } from "fs";
+import { join } from "path";
+
+// src/utils/open-browser.ts
+async function openBrowser(filePath) {
+  try {
+    const open = await import("open");
+    await open.default(filePath);
+  } catch {
+    console.log(`Could not open browser automatically. Open this file manually:`);
+    console.log(`  ${filePath}`);
+  }
+}
+
+// src/cli/output/html.ts
+function generateTreemapHTML(result) {
+  const dataJson = JSON.stringify(result.tree);
+  const mode = result.mode;
+  const repoName = result.repoName;
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>GitFamiliar \u2014 ${repoName}</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+    background: #1a1a2e;
+    color: #e0e0e0;
+    overflow: hidden;
+  }
+  #header {
+    padding: 16px 24px;
+    background: #16213e;
+    border-bottom: 1px solid #0f3460;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+  #header h1 { font-size: 18px; color: #e94560; }
+  #header .info { font-size: 14px; color: #a0a0a0; }
+  #breadcrumb {
+    padding: 8px 24px;
+    background: #16213e;
+    font-size: 13px;
+    border-bottom: 1px solid #0f3460;
+  }
+  #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;
+    pointer-events: none;
+    background: rgba(22, 33, 62, 0.95);
+    border: 1px solid #0f3460;
+    border-radius: 6px;
+    padding: 10px 14px;
+    font-size: 13px;
+    line-height: 1.6;
+    display: none;
+    z-index: 100;
+    max-width: 300px;
+  }
+  #legend {
+    position: absolute;
+    bottom: 16px;
+    right: 16px;
+    background: rgba(22, 33, 62, 0.9);
+    border: 1px solid #0f3460;
+    border-radius: 6px;
+    padding: 10px;
+    font-size: 12px;
+  }
+  #legend .gradient-bar {
+    width: 120px;
+    height: 12px;
+    background: linear-gradient(to right, #e94560, #f5a623, #27ae60);
+    border-radius: 3px;
+    margin: 4px 0;
+  }
+  #legend .labels { display: flex; justify-content: space-between; font-size: 10px; color: #888; }
+</style>
+</head>
+<body>
+<div id="header">
+  <h1>GitFamiliar \u2014 ${repoName}</h1>
+  <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">
+  <div>Familiarity</div>
+  <div class="gradient-bar"></div>
+  <div class="labels"><span>0%</span><span>50%</span><span>100%</span></div>
+</div>
+
+<script src="https://d3js.org/d3.v7.min.js"></script>
+<script>
+const rawData = ${dataJson};
+const mode = "${mode}";
+let currentFilter = 'all';
+let currentPath = '';
+
+function scoreColor(score) {
+  if (score <= 0) return '#e94560';
+  if (score >= 1) return '#27ae60';
+  if (score < 0.5) {
+    const t = score / 0.5;
+    return d3.interpolateRgb('#e94560', '#f5a623')(t);
+  }
+  const t = (score - 0.5) / 0.5;
+  return d3.interpolateRgb('#f5a623', '#27ae60')(t);
+}
+
+function getFileScore(file) {
+  if (mode !== 'binary') return file.score;
+  if (currentFilter === 'written') return file.isWritten ? 1 : 0;
+  if (currentFilter === 'reviewed') return file.isReviewed ? 1 : 0;
+  return file.score;
+}
+
+function findNode(node, path) {
+  if (node.path === path) return node;
+  if (node.children) {
+    for (const child of node.children) {
+      const found = findNode(child, path);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+
+function flattenFiles(node) {
+  const files = [];
+  function walk(n) {
+    if (n.type === 'file') {
+      files.push(n);
+    } else if (n.children) {
+      n.children.forEach(walk);
+    }
+  }
+  walk(node);
+  return files;
+}
+
+function render() {
+  const container = document.getElementById('treemap');
+  container.innerHTML = '';
+
+  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 targetNode = currentPath ? findNode(rawData, currentPath) : rawData;
+  if (!targetNode) return;
+
+  const hierarchyData = {
+    name: targetNode.path || 'root',
+    children: (targetNode.children || []).map(function buildChild(c) {
+      if (c.type === 'file') {
+        return { name: c.path.split('/').pop(), data: c, value: Math.max(1, c.lines) };
+      }
+      return {
+        name: c.path.split('/').pop(),
+        data: c,
+        children: (c.children || []).map(buildChild),
+      };
+    }),
+  };
+
+  const root = d3.hierarchy(hierarchyData)
+    .sum(d => d.value || 0)
+    .sort((a, b) => (b.value || 0) - (a.value || 0));
+
+  d3.treemap()
+    .size([width, height])
+    .padding(2)
+    .paddingTop(18)
+    .round(true)(root);
+
+  const svg = d3.select('#treemap')
+    .append('svg')
+    .attr('width', width)
+    .attr('height', height);
+
+  const tooltip = document.getElementById('tooltip');
+
+  // Draw groups (folders)
+  const groups = svg.selectAll('g')
+    .data(root.descendants().filter(d => d.depth > 0))
+    .join('g')
+    .attr('transform', d => \`translate(\${d.x0},\${d.y0})\`);
+
+  groups.append('rect')
+    .attr('width', d => Math.max(0, d.x1 - d.x0))
+    .attr('height', d => Math.max(0, d.y1 - d.y0))
+    .attr('fill', d => {
+      if (d.data.data) {
+        const score = d.children ? d.data.data.score : getFileScore(d.data.data);
+        return scoreColor(score);
+      }
+      return '#333';
+    })
+    .attr('opacity', d => d.children ? 0.3 : 0.85)
+    .attr('stroke', '#1a1a2e')
+    .attr('stroke-width', 1)
+    .attr('rx', 2)
+    .style('cursor', d => d.children ? 'pointer' : 'default')
+    .on('click', (event, d) => {
+      if (d.children && d.data.data && d.data.data.type === 'folder') {
+        zoomTo(d.data.data.path);
+      }
+    })
+    .on('mouseover', (event, d) => {
+      if (!d.data.data) return;
+      const data = d.data.data;
+      const name = data.path || d.data.name;
+      const score = d.children ? data.score : getFileScore(data);
+      let html = \`<strong>\${name}</strong><br>Score: \${Math.round(score * 100)}%<br>Lines: \${data.lines}\`;
+      if (data.type === 'folder') {
+        html += \`<br>Files: \${data.fileCount}\`;
+      }
+      if (data.blameScore !== undefined) {
+        html += \`<br>Blame: \${Math.round(data.blameScore * 100)}%\`;
+      }
+      if (data.commitScore !== undefined) {
+        html += \`<br>Commit: \${Math.round(data.commitScore * 100)}%\`;
+      }
+      if (data.reviewScore !== undefined) {
+        html += \`<br>Review: \${Math.round(data.reviewScore * 100)}%\`;
+      }
+      tooltip.innerHTML = html;
+      tooltip.style.display = 'block';
+    })
+    .on('mousemove', (event) => {
+      tooltip.style.left = (event.pageX + 12) + 'px';
+      tooltip.style.top = (event.pageY - 12) + 'px';
+    })
+    .on('mouseout', () => {
+      tooltip.style.display = 'none';
+    });
+
+  // Labels
+  groups.append('text')
+    .attr('x', 4)
+    .attr('y', 13)
+    .attr('fill', '#fff')
+    .attr('font-size', '11px')
+    .attr('font-weight', d => d.children ? 'bold' : 'normal')
+    .text(d => {
+      const w = (d.x1 - d.x0);
+      const name = d.data.name || '';
+      if (w < 40) return '';
+      if (w < name.length * 7) return name.slice(0, Math.floor(w / 7)) + '..';
+      return name;
+    });
+}
+
+function zoomTo(path) {
+  currentPath = path;
+  updateBreadcrumb();
+  render();
+}
+
+function updateBreadcrumb() {
+  const el = document.getElementById('breadcrumb');
+  const parts = currentPath ? currentPath.split('/') : [];
+  let html = '<span onclick="zoomTo(\\'\\')">root</span>';
+  let accumulated = '';
+  for (const part of parts) {
+    accumulated = accumulated ? accumulated + '/' + part : part;
+    const p = accumulated;
+    html += \`<span class="sep">/</span><span onclick="zoomTo('\${p}')">\${part}</span>\`;
+  }
+  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>
+</body>
+</html>`;
+}
+async function generateAndOpenHTML(result, repoPath) {
+  const html = generateTreemapHTML(result);
+  const outputPath = join(repoPath, "gitfamiliar-report.html");
+  writeFileSync(outputPath, html, "utf-8");
+  console.log(`Report generated: ${outputPath}`);
+  await openBrowser(outputPath);
+}
+
+// src/cli/index.ts
+function createProgram() {
+  const program2 = new Command();
+  program2.name("gitfamiliar").description("Visualize your code familiarity from Git history").version("0.1.0").option("-m, --mode <mode>", "Scoring mode: binary, authorship, review-coverage, weighted", "binary").option("-u, --user <user>", "Git user name or email (defaults to git config)").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")').action(async (rawOptions) => {
+    try {
+      const repoPath = process.cwd();
+      const options = parseOptions(rawOptions, repoPath);
+      const result = await computeFamiliarity(options);
+      if (options.html) {
+        await generateAndOpenHTML(result, repoPath);
+      } else {
+        renderTerminal(result);
+      }
+    } catch (error) {
+      console.error(`Error: ${error.message}`);
+      process.exit(1);
+    }
+  });
+  return program2;
+}
+
+// bin/gitfamiliar.ts
+var program = createProgram();
+program.parse();
+//# sourceMappingURL=gitfamiliar.js.map