per capita

Author: OhadPerryBoomi

cli/team_config.py

@@ -1,11 +1,15 @@
 """Team mapping configuration for developer-to-team assignment."""
 
+import logging
 import re
+from datetime import date, timedelta
 from pathlib import Path
-from typing import Dict, Optional
+from typing import Dict, List, Optional
 
 import yaml
 
+logger = logging.getLogger(__name__)
+
 
 def _parse_team_assignments_text(content: str) -> Dict[str, str]:
     """
@@ -159,3 +163,152 @@ def get_team_for_repo(owner: str, repo: str, mapping: Optional[Dict[str, str]] =
     Kept for backward compatibility; returns empty string.
     """
     return ""
+
+
+# ---------------------------------------------------------------------------
+# Developer tenure (start/end dates) for headcount calculations
+# ---------------------------------------------------------------------------
+
+_TENURE_FILENAME = "developer-tenure.yaml"
+
+
+def _parse_date_field(val: object) -> Optional[date]:
+    if not val:
+        return None
+    try:
+        return date.fromisoformat(str(val))
+    except (ValueError, TypeError):
+        return None
+
+
+def _parse_leaves(raw_leaves: object) -> List[Dict[str, date]]:
+    """Parse a list of ``{from: ..., to: ...}`` leave ranges."""
+    if not isinstance(raw_leaves, list):
+        return []
+    result: List[Dict[str, date]] = []
+    for entry in raw_leaves:
+        if not isinstance(entry, dict):
+            continue
+        leave_from = _parse_date_field(entry.get("from"))
+        leave_to = _parse_date_field(entry.get("to"))
+        if leave_from and leave_to:
+            result.append({"from": leave_from, "to": leave_to})
+    return result
+
+
+def load_developer_tenure(
+    cwd: Optional[Path] = None,
+) -> Dict[str, dict]:
+    """Load developer start/end dates and leave ranges from developer-tenure.yaml.
+
+    Returns dict keyed by GitHub username::
+
+        {"alice": {"start": date(2024,1,1), "end": None, "leaves": [...]}, ...}
+
+    Each leave entry is ``{"from": date, "to": date}``.
+    """
+    base = cwd or Path.cwd()
+    path = base / _TENURE_FILENAME
+    if not path.exists():
+        logger.warning("%s not found – headcount will fall back to CSV-derived counts", _TENURE_FILENAME)
+        return {}
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except Exception as exc:
+        logger.warning("Failed to parse %s: %s", _TENURE_FILENAME, exc)
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    devs_raw = data.get("developers", data)
+    if not isinstance(devs_raw, dict):
+        return {}
+
+    result: Dict[str, dict] = {}
+    for username, info in devs_raw.items():
+        if not isinstance(info, dict):
+            continue
+        start_date = _parse_date_field(info.get("start"))
+        if start_date is None:
+            continue
+        result[str(username).strip()] = {
+            "start": start_date,
+            "end": _parse_date_field(info.get("end")),
+            "leaves": _parse_leaves(info.get("leaves")),
+        }
+    return result
+
+
+def _is_on_leave(week_start: date, week_end: date, leaves: List[Dict[str, date]]) -> bool:
+    """True if any leave range fully covers the week (from <= week_start and to >= week_end)."""
+    for lv in leaves:
+        if lv["from"] <= week_start and lv["to"] >= week_end:
+            return True
+    return False
+
+
+def get_active_headcount(
+    week_start: date,
+    team: Optional[str] = None,
+    tenure: Optional[Dict[str, dict]] = None,
+    team_mapping: Optional[Dict[str, str]] = None,
+) -> int:
+    """Return the number of developers active during the week starting at *week_start*.
+
+    A developer is active if ``start <= week_end`` and (``end`` is None or
+    ``end >= week_start``) and they are not on leave for the entire week.
+
+    Args:
+        week_start: Monday of the ISO week.
+        team: If given, only count developers belonging to this team.
+        tenure: Pre-loaded tenure dict (from :func:`load_developer_tenure`).
+        team_mapping: Pre-loaded team mapping (from :func:`load_team_mapping`).
+    """
+    if tenure is None:
+        tenure = load_developer_tenure()
+    if team_mapping is None:
+        team_mapping = load_team_mapping()
+
+    week_end = week_start + timedelta(days=6)
+    count = 0
+    for dev, info in tenure.items():
+        start = info["start"]
+        end = info.get("end")
+        if start is None or start > week_end:
+            continue
+        if end is not None and end < week_start:
+            continue
+        if team is not None and team_mapping.get(dev, "") != team:
+            continue
+        if _is_on_leave(week_start, week_end, info.get("leaves", [])):
+            continue
+        count += 1
+    return count
+
+
+def get_weekly_headcounts(
+    weeks: List[date],
+    teams: Optional[List[str]] = None,
+    cwd: Optional[Path] = None,
+) -> Dict[str, List[int]]:
+    """Compute headcount for each week, for 'All Teams' and each team.
+
+    Returns::
+
+        {"All Teams": [12, 13, ...], "Core": [5, 5, ...], ...}
+    """
+    tenure = load_developer_tenure(cwd)
+    team_mapping = load_team_mapping(cwd)
+
+    if teams is None:
+        teams = sorted({t for t in team_mapping.values() if t and t != "Bots"})
+
+    result: Dict[str, List[int]] = {"All Teams": []}
+    for t in teams:
+        result[t] = []
+
+    for w in weeks:
+        result["All Teams"].append(get_active_headcount(w, team=None, tenure=tenure, team_mapping=team_mapping))
+        for t in teams:
+            result[t].append(get_active_headcount(w, team=t, tenure=tenure, team_mapping=team_mapping))
+
+    return result

developer-tenure.yaml

@@ -0,0 +1,108 @@
+# Developer employment/tenure dates.
+# start: first day the developer was active (required)
+# end:   last day (omit or leave null if still active)
+# leaves: optional list of absence ranges (maternity, sabbatical, etc.)
+#         each entry has "from" and "to" dates (inclusive)
+#
+# Example with leave:
+#   alice:
+#     start: "2023-01-15"
+#     leaves:
+#       - { from: "2025-06-01", to: "2025-09-30" }   # maternity
+#
+# Used by the "Velocity Per Capita" chart to compute active headcount
+# per week. Team membership comes from github-teams.cfg.
+
+developers:
+  # ── Core ──
+  OhadPerryBoomi:
+    start: "2025-05-01"
+  nvgoldin:
+    start: "2024-01-01"
+  orhss:
+    start: "2024-01-01"
+  OmerBor:
+    start: "2024-01-01"
+  hadasdd:
+    start: "2024-01-01"
+  noamtzu:
+    start: "2024-01-01"
+    end: "2025-12-01"
+  OronW:
+    start: "2024-01-01"
+    end: "2026-01-01"
+
+  # ── FullStack ──
+  shiran1989:
+    start: "2024-01-01"
+  Morzus90:
+    start: "2024-01-01"
+  Inara-Rivery:
+    start: "2024-01-01"
+  yairabramovitch:
+    start: "2024-01-01"
+    leaves:
+      - { from: "2026-02-01", to: "2026-03-01" }
+  # FeiginNastia:
+    # start: "2024-01-01"
+  noam-salomon:
+    start: "2024-01-01"
+
+  # ── Integration ──
+  RonKlar90:
+    start: "2024-01-01"
+  OmerMordechai1:
+    start: "2024-01-01"
+  Lizkhrapov:
+    start: "2024-01-01"
+  Amichai-B:
+    start: "2024-01-01"
+
+  # ── CDC ──
+  aaronabv:
+    start: "2024-01-01"
+  sigalikanevsky:
+    start: "2024-01-01"
+  eitamring:
+    start: "2024-01-01"
+  Omri-Groen:
+    start: "2024-01-01"
+  shristiguptaa:
+    start: "2024-01-01"
+
+  # ── Ninja ──
+  pocha-vijaymohanreddy:
+    start: "2024-01-01"
+  mayanks-Boomi:
+    start: "2024-01-01"
+  Srivasu-Boomi:
+    start: "2024-01-01"
+  vijay-prakash-singh-dev:
+    start: "2024-01-01"
+  bharat-boomi:
+    start: "2024-01-01"
+  vs1328:
+    start: "2024-01-01"
+
+  # ── Devops ──
+  alonalmog82:
+    start: "2024-01-01"
+  EdenReuveniRivery:
+    start: "2024-01-01"
+    leaves:
+      - { from: "2025-12-01", to: "2026-05-01" }
+  Alonreznik:
+    start: "2024-01-01"
+  devops-rivery:
+    start: "2024-01-01"
+  # Mikeygoldman1:
+    # start: "2024-01-01"
+  RavikiranDK:
+    start: "2024-01-01"
+  Chen-Poli:
+    start: "2024-01-01"
+    end: "2025-09-01"
+  livninoam:
+    start: "2024-01-01"
+    end: "2025-07-01"
+

reports/basic/__init__.py

@@ -1,4 +1,4 @@
-"""Basic operational reports (1-3, 7, 18, 19)."""
+"""Basic operational reports (1-3, 7, 18, 19, 22)."""
 
 from .reports import (
     report_avg_complexity_rolling as report_avg_complexity_rolling,
@@ -7,4 +7,5 @@
     report_complexity_volume_over_time as report_complexity_volume_over_time,
     report_high_complexity_frequency as report_high_complexity_frequency,
     report_pr_count_vs_complexity as report_pr_count_vs_complexity,
+    report_velocity_per_capita as report_velocity_per_capita,
 )

reports/basic/reports.py

@@ -7,6 +7,7 @@
 import matplotlib.pyplot as plt
 import pandas as pd
 
+from cli.team_config import get_weekly_headcounts
 from reports.validation import has_plottable_agg, has_plottable_series, validate_png_has_content
 
 
@@ -203,3 +204,61 @@ def report_high_complexity_frequency(df: pd.DataFrame, output_dir: Path) -> Opti
     fig.savefig(out, dpi=150, bbox_inches="tight")
     plt.close(fig)
     return str(out) if validate_png_has_content(out) else None
+
+
+def report_velocity_per_capita(df: pd.DataFrame, output_dir: Path) -> Optional[str]:
+    """Report 22: Velocity Per Capita – weekly complexity / active headcount."""
+    df = _ensure_date(df)
+    if df.empty:
+        return None
+    df = df.copy()
+    df["week"] = pd.to_datetime(df["date"]).dt.to_period("W").dt.start_time
+    weekly_vel = df.groupby("week")["complexity"].sum().sort_index()
+    if not has_plottable_series(weekly_vel, min_points=2):
+        return None
+
+    week_dates = [w.date() for w in weekly_vel.index]
+    df["team"] = df.get("team", pd.Series([""] * len(df))).fillna("").replace("", "Unknown")
+    teams = sorted(t for t in df["team"].unique() if t and t != "Unknown")
+    headcounts = get_weekly_headcounts(week_dates, teams=teams or None)
+
+    fig, ax = plt.subplots(figsize=(14, 6))
+
+    hc_all = headcounts.get("All Teams", [])
+    if hc_all:
+        per_capita = [
+            float(weekly_vel.iloc[i]) / max(h, 1) for i, h in enumerate(hc_all)
+        ]
+        ax.plot(weekly_vel.index, per_capita, "k-o", markersize=4, linewidth=2, label="All Teams")
+
+    for team_name in teams:
+        team_weekly = (
+            df[df["team"] == team_name]
+            .groupby("week")["complexity"]
+            .sum()
+            .reindex(weekly_vel.index, fill_value=0)
+        )
+        hc_team = headcounts.get(team_name, [])
+        if not hc_team:
+            continue
+        per_capita_team = [
+            float(team_weekly.iloc[i]) / max(h, 1) for i, h in enumerate(hc_team)
+        ]
+        ax.plot(weekly_vel.index, per_capita_team, "-o", markersize=3, label=team_name)
+
+    ax.set_title(
+        "Velocity Per Capita (by Week)\n"
+        "What: Complexity output per active developer. When: Normalize for headcount changes. "
+        "How: Total complexity / active developers each week."
+    )
+    ax.set_ylabel("Complexity / Developer")
+    ax.set_xlabel("Week")
+    ax.legend(loc="upper left", fontsize=8, ncol=2)
+    ax.tick_params(axis="x", rotation=45)
+    ax.xaxis.set_major_formatter(mdates.DateFormatter("%Y-%m-%d"))
+    ax.set_ylim(bottom=0)
+    fig.tight_layout()
+    out = output_dir / "22-velocity-per-capita.png"
+    fig.savefig(out, dpi=150, bbox_inches="tight")
+    plt.close(fig)
+    return str(out) if validate_png_has_content(out) else None