#!/usr/bin/env python3 """ repo_stats.py - turn your team's Git history and AI_LOG.md into data and figures for a "human-in-the-loop vibe-coded software engineering" case study. Research Methodology, CBNU, Fall 2026. USAGE (run from anywhere; Python 3.8+, git, matplotlib): pip install matplotlib python repo_stats.py path/to/your/repo python repo_stats.py path/to/your/repo --event 2026-10-15 "Applied SE principles" OUTPUT (in path/to/your/repo/analysis/ unless you use --out): commits.csv one row per commit (authors replaced by Dev1, Dev2, ...) weekly.csv one row per week: commits, AI-tagged commits, lines added/deleted, churn ai_log.csv one row per AI_LOG.md entry: date, week, task type, tool table1.md TABLE I (dataset summary) in Markdown - copy the numbers into your paper fig1_churn.png Fig. 1: code churn per week (line graph) fig2_ai_tasks.png Fig. 2: AI_LOG entries by task type (bar chart) fig3_commits.png Fig. 3: AI-tagged vs. other commits per week (grouped bars) DEFINITIONS (put these in your Methods section and cite git-log [IEEE]): churn = lines added + lines deleted (from `git log --numstat`) AI-tagged = a commit whose message has a Co-authored-by line naming an AI tool, or contains [ai] / (ai) / "AI-assisted" / "generated by" (edit AI_PATTERNS) AI_LOG entry = a heading or list line in AI_LOG.md that contains a date (YYYY-MM-DD) task type = first matching keyword group in TASK_TYPES (edit it for your log) ETHICS: use only YOUR team's repository, with your teammates' agreement. Author names are replaced by Dev1, Dev2, ... Do not publish commit messages that contain names, emails, or keys. """ import argparse, csv, datetime as dt, os, re, subprocess, sys from collections import Counter, defaultdict # ---------- things you may want to edit ---------- EXCLUDE = [r"(^|/)node_modules/", r"(^|/)dist/", r"(^|/)build/", r"(^|/)\.next/", r"(^|/)venv/", r"(^|/)\.venv/", r"package-lock\.json$", r"yarn\.lock$", r"pnpm-lock\.yaml$", r"poetry\.lock$", r"\.min\.(js|css)$", r"(^|/)analysis/"] AI_PATTERNS = [r"co-authored-by:.*(claude|anthropic|copilot|cursor|gemini|chatgpt|openai|codex|windsurf)", r"\[ai\]", r"\(ai\)", r"ai-assisted", r"generated (by|with)", r"🤖"] TASK_TYPES = [ # (label, keywords) - first match wins, so order matters ("Debug / fix", ["fix", "bug", "error", "debug", "crash", "broken", "issue"]), ("Refactor / clean", ["refactor", "clean", "rename", "lint", "format", "simplify"]), ("Test", ["test", "pytest", "jest", "coverage"]), ("Explain / learn", ["explain", "understand", "learn", "why", "how does"]), ("Docs", ["readme", "doc", "comment", "documentation"]), ("Generate feature", ["add", "create", "generate", "build", "implement", "feature", "new"]), ] TOOLS = ["claude", "chatgpt", "gemini", "copilot", "cursor", "codex", "windsurf"] # -------------------------------------------------- def git(repo, *args): r = subprocess.run(["git", "-C", repo, *args], capture_output=True, text=True, encoding="utf-8", errors="replace") if r.returncode != 0: sys.exit("git error: " + r.stderr.strip()) return r.stdout def week_start(d): return d - dt.timedelta(days=d.weekday()) # Monday of that week def excluded(path): return any(re.search(p, path) for p in EXCLUDE) def read_commits(repo, since): extra = [f"--since={since}"] if since else [] # pass 1: metadata (fields separated by 0x1f, commits by 0x1e) meta_raw = git(repo, "log", "--no-merges", *extra, "--pretty=format:%H%x1f%ad%x1f%aN%x1f%s%x1f%b%x1e", "--date=short") commits, order = {}, [] for rec in meta_raw.split("\x1e"): rec = rec.strip("\n") if not rec: continue h, date, author, subj, body = (rec.split("\x1f") + [""] * 5)[:5] text = (subj + "\n" + body).lower() commits[h] = dict(hash=h[:8], date=date, author=author, subject=subj, ai=int(any(re.search(p, text) for p in AI_PATTERNS)), files=0, added=0, deleted=0) order.append(h) # pass 2: line counts num_raw = git(repo, "log", "--no-merges", *extra, "--numstat", "--pretty=format:@@%H") cur = None for line in num_raw.splitlines(): if line.startswith("@@"): cur = commits.get(line[2:].strip()) continue parts = line.split("\t") if cur is None or len(parts) != 3 or parts[0] == "-": # "-" = binary file continue if excluded(parts[2]): continue cur["files"] += 1 cur["added"] += int(parts[0]) cur["deleted"] += int(parts[1]) rows = sorted((commits[h] for h in reversed(order)), key=lambda c: c["date"]) # oldest first devs = {} for c in rows: devs.setdefault(c["author"], f"Dev{len(devs) + 1}") c["author"] = devs[c["author"]] c["churn"] = c["added"] + c["deleted"] c["week"] = week_start(dt.date.fromisoformat(c["date"])).isoformat() return rows, len(devs) def read_ai_log(path): if not os.path.exists(path): return [] entries, cur = [], None date_re = re.compile(r"(20\d\d-\d\d-\d\d)") for line in open(path, encoding="utf-8", errors="replace"): m = date_re.search(line) if m and (line.lstrip().startswith(("#", "-", "*", "|")) or line[:1].isdigit()): cur = {"date": m.group(1), "text": line.strip()} entries.append(cur) elif cur is not None: cur["text"] += " " + line.strip() out = [] for e in entries: t = e["text"].lower() task = next((lab for lab, kws in TASK_TYPES if any(k in t for k in kws)), "Other") tool = next((x for x in TOOLS if x in t), "unknown") d = dt.date.fromisoformat(e["date"]) out.append(dict(date=e["date"], week=week_start(d).isoformat(), task_type=task, tool=tool, preview=e["text"][:70])) return out def weekly(rows): w = defaultdict(lambda: dict(commits=0, ai_commits=0, added=0, deleted=0, churn=0)) for c in rows: x = w[c["week"]] x["commits"] += 1; x["ai_commits"] += c["ai"] x["added"] += c["added"]; x["deleted"] += c["deleted"]; x["churn"] += c["churn"] if not w: return [] weeks, d = [], dt.date.fromisoformat(min(w)) last = dt.date.fromisoformat(max(w)) while d <= last: # include empty weeks so the time axis is honest k = d.isoformat() weeks.append(dict(week=k, **w[k]) if k in w else dict(week=k, commits=0, ai_commits=0, added=0, deleted=0, churn=0)) d += dt.timedelta(days=7) return weeks def write_csv(path, rows, fields): with open(path, "w", newline="", encoding="utf-8") as f: wr = csv.DictWriter(f, fieldnames=fields, extrasaction="ignore") wr.writeheader(); wr.writerows(rows) def table1(rows, ndev, weeks, log): added = sum(c["added"] for c in rows); deleted = sum(c["deleted"] for c in rows) ai = sum(c["ai"] for c in rows) lines = [ "TABLE I. DATASET SUMMARY", "", "| Measure | Value |", "|---|---|", f"| Period | {rows[0]['date']} to {rows[-1]['date']} ({len(weeks)} weeks) |", f"| Developers | {ndev} |", f"| Commits (no merges) | {len(rows)} |", f"| AI-tagged commits | {ai} ({100 * ai / len(rows):.0f}%) |", f"| Lines added / deleted | {added:,} / {deleted:,} |", f"| Median churn per commit | {sorted(c['churn'] for c in rows)[len(rows) // 2]:,} lines |", f"| AI_LOG.md entries | {len(log)} |", ] return "\n".join(lines) + "\n" def figures(out, weeks, log, events): import matplotlib matplotlib.use("Agg") import matplotlib.pyplot as plt plt.rcParams.update({"font.size": 8, "font.family": "serif", "axes.spines.top": False, "axes.spines.right": False, "savefig.dpi": 300}) W = 3.5 # IEEE single-column width in inches labels = [str(i + 1) for i in range(len(weeks))] # week 1, 2, 3, ... xlabel = f"Week (week 1 starts {weeks[0]['week']})" x = list(range(len(weeks))) step = max(1, -(-len(x) // 12)) def add_events(ax): for date, text in events: k = week_start(dt.date.fromisoformat(date)).isoformat() if k in [w["week"] for w in weeks]: i = [w["week"] for w in weeks].index(k) ax.axvline(i, color="0.4", ls="--", lw=0.8) ax.text(i + 0.15, ax.get_ylim()[1] * 0.95, text, fontsize=7, va="top") # Fig. 1 churn per week fig, ax = plt.subplots(figsize=(W, 2.2)) ax.plot(x, [w["churn"] for w in weeks], "-o", color="black", ms=3, lw=1) ax.set_ylim(0, max(1, max(w["churn"] for w in weeks)) * 1.15) ax.set_xticks(x[::step]); ax.set_xticklabels(labels[::step]) ax.set_xlabel(xlabel); ax.set_ylabel("Churn (lines added + deleted)") ax.grid(axis="y", color="0.9", lw=0.5) add_events(ax) fig.tight_layout(); fig.savefig(os.path.join(out, "fig1_churn.png")); plt.close(fig) # Fig. 2 AI_LOG entries by task type, sorted if log: cnt = Counter(e["task_type"] for e in log).most_common()[::-1] fig, ax = plt.subplots(figsize=(W, 0.4 + 0.28 * len(cnt))) ax.barh([k for k, _ in cnt], [v for _, v in cnt], color="0.35") for i, (_, v) in enumerate(cnt): ax.text(v + 0.2, i, str(v), va="center", fontsize=7) ax.set_xlabel("AI_LOG.md entries"); ax.spines["left"].set_visible(False) ax.tick_params(axis="y", length=0) fig.tight_layout(); fig.savefig(os.path.join(out, "fig2_ai_tasks.png")); plt.close(fig) # Fig. 3 AI-tagged vs other commits per week (grouped bars, hatch = not color alone) fig, ax = plt.subplots(figsize=(W, 2.2)) ai = [w["ai_commits"] for w in weeks]; other = [w["commits"] - w["ai_commits"] for w in weeks] ax.bar([i - 0.2 for i in x], other, 0.4, color="white", edgecolor="black", lw=0.6, label="Other commits") ax.bar([i + 0.2 for i in x], ai, 0.4, color="0.3", edgecolor="black", lw=0.6, hatch="///", label="AI-tagged") ax.set_xticks(x[::step]); ax.set_xticklabels(labels[::step]) ax.set_xlabel(xlabel); ax.set_ylabel("Commits") ax.set_ylim(0, max(1, max(w["commits"] for w in weeks)) * 1.2) ax.legend(frameon=False, fontsize=7, ncol=2, loc="lower center", bbox_to_anchor=(0.5, 1.0)) add_events(ax) fig.tight_layout(); fig.savefig(os.path.join(out, "fig3_commits.png")); plt.close(fig) def main(): ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) ap.add_argument("repo", nargs="?", default=".") ap.add_argument("--out", help="output folder (default: /analysis)") ap.add_argument("--ai-log", default="AI_LOG.md", help="path inside the repo (default AI_LOG.md)") ap.add_argument("--since", help="only commits after this date, e.g. 2026-09-01") ap.add_argument("--event", nargs=2, action="append", default=[], metavar=("DATE", "LABEL"), help='mark a date on the figures, e.g. --event 2026-10-15 "SE principles"') ap.add_argument("--no-figures", action="store_true") a = ap.parse_args() out = a.out or os.path.join(a.repo, "analysis") os.makedirs(out, exist_ok=True) rows, ndev = read_commits(a.repo, a.since) if not rows: sys.exit("No commits found.") log = read_ai_log(os.path.join(a.repo, a.ai_log)) weeks = weekly(rows) write_csv(os.path.join(out, "commits.csv"), rows, ["hash", "date", "week", "author", "ai", "files", "added", "deleted", "churn", "subject"]) write_csv(os.path.join(out, "weekly.csv"), weeks, ["week", "commits", "ai_commits", "added", "deleted", "churn"]) write_csv(os.path.join(out, "ai_log.csv"), log, ["date", "week", "task_type", "tool", "preview"]) t1 = table1(rows, ndev, weeks, log) open(os.path.join(out, "table1.md"), "w", encoding="utf-8").write(t1) if not a.no_figures: figures(out, weeks, log, a.event) print(t1) print(f"Saved CSV files, table1.md and figures in: {out}") if not log: print(f"Note: no dated entries found in {a.ai_log}. Use one date (YYYY-MM-DD) per entry heading.") if __name__ == "__main__": main()