codepulse-cli 0.1.0__py3-none-any.whl

codepulse/__init__.py

@@ -0,0 +1,3 @@
+"""CodePulse — reveal a codebase's health from its git history."""
+
+__version__ = "0.1.0"

codepulse/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

codepulse/analyzers.py

@@ -0,0 +1,468 @@
+"""Turn raw commit history into code-health signals.
+
+The headline idea: history reveals things static linters can't. A file that
+is both *complex* and *changed constantly* is where bugs are born. A file only
+one person ever touches is a staffing risk. Files that always change together
+are secretly coupled.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import os
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from fnmatch import fnmatch
+
+from . import complexity as _complexity
+from .git_data import Commit
+
+# Files that are generated, vendored, or pure data — real churn, but not code
+# whose health tells you anything. Excluded by default so they don't crowd out
+# the files that actually matter.
+DEFAULT_IGNORE: tuple[str, ...] = (
+    "*.lock", "Cargo.lock", "package-lock.json", "yarn.lock",
+    "pnpm-lock.yaml", "poetry.lock", "composer.lock", "Gemfile.lock",
+    "*.tsv", "*.csv",
+    "*.min.js", "*.min.css", "*.map", "*.snap",
+    # Binary assets: real churn, but no code health to measure.
+    "*.ttf", "*.otf", "*.woff", "*.woff2", "*.eot",
+    "*.png", "*.jpg", "*.jpeg", "*.gif", "*.ico", "*.svg", "*.webp", "*.pdf",
+    "*.zip", "*.gz", "*.jar", "*.mp3", "*.mp4", "*.wav",
+    "node_modules/*", "*/node_modules/*",
+    "dist/*", "*/dist/*", "build/*", "*/build/*",
+    "vendor/*", "*/vendor/*", "*/.next/*",
+)
+
+
+def is_ignored(path: str, patterns) -> bool:
+    """True if the path matches any glob pattern (whole path or basename)."""
+    base = path.rsplit("/", 1)[-1]
+    return any(fnmatch(path, p) or fnmatch(base, p) for p in patterns)
+
+
+def filter_commits(commits: list[Commit], patterns) -> list[Commit]:
+    """Drop ignored files from each commit, keeping the commit itself.
+
+    The commit still counts toward totals and author activity; only its ignored
+    file changes are removed, so hotspots/coupling/bus-factor ignore them too.
+    """
+    if not patterns:
+        return commits
+    out: list[Commit] = []
+    for c in commits:
+        kept = [fc for fc in c.files if not is_ignored(fc.path, patterns)]
+        out.append(Commit(hash=c.hash, timestamp=c.timestamp, author=c.author, files=kept))
+    return out
+
+
+@dataclass
+class FileStat:
+    """Accumulated history for a single file path."""
+
+    path: str
+    commits: int = 0
+    authors: Counter = field(default_factory=Counter)  # author -> commits
+    added: int = 0
+    deleted: int = 0
+    last_timestamp: int = 0
+    loc: int = 0  # current line count in the working tree
+    complexity: int = 0  # estimated decision points (see complexity.py)
+    exists: bool = True  # still present on disk?
+
+    @property
+    def num_authors(self) -> int:
+        return len(self.authors)
+
+    @property
+    def main_owner(self) -> tuple[str | None, float]:
+        """Top contributor and their share of this file's commits."""
+        if not self.authors:
+            return None, 0.0
+        owner, count = self.authors.most_common(1)[0]
+        total = sum(self.authors.values())
+        return owner, count / total
+
+    @property
+    def hotspot_score(self) -> int:
+        """Change frequency x complexity. High = complex AND churned."""
+        return self.commits * self.complexity
+
+
+def _measure_file(path: str) -> tuple[int, int]:
+    try:
+        with open(path, "rb") as fh:
+            return _complexity.measure(fh.read())
+    except Exception:
+        return 0, 0
+
+
+def build_file_stats(commits: list[Commit], repo: str) -> dict[str, FileStat]:
+    stats: dict[str, FileStat] = {}
+    for commit in commits:
+        for change in commit.files:
+            stat = stats.get(change.path)
+            if stat is None:
+                stat = FileStat(path=change.path)
+                stats[change.path] = stat
+            stat.commits += 1
+            stat.authors[commit.author] += 1
+            stat.added += change.added
+            stat.deleted += change.deleted
+            stat.last_timestamp = max(stat.last_timestamp, commit.timestamp)
+
+    for stat in stats.values():
+        full = os.path.join(repo, stat.path.replace("/", os.sep))
+        if os.path.isfile(full):
+            stat.loc, stat.complexity = _measure_file(full)
+            stat.exists = True
+        else:
+            stat.exists = False
+
+    return stats
+
+
+def hotspots(stats: dict[str, FileStat], limit: int = 20) -> list[FileStat]:
+    present = [s for s in stats.values() if s.exists and s.loc > 0]
+    present.sort(key=lambda s: s.hotspot_score, reverse=True)
+    return present[:limit]
+
+
+def bus_factor_risks(stats: dict[str, FileStat], limit: int = 20, min_commits: int = 3) -> list[FileStat]:
+    """Files actively maintained by exactly one person."""
+    risky = [
+        s for s in stats.values()
+        if s.exists and s.commits >= min_commits and s.num_authors == 1
+    ]
+    risky.sort(key=lambda s: s.commits, reverse=True)
+    return risky[:limit]
+
+
+@dataclass
+class CouplingPair:
+    a: str
+    b: str
+    shared: int  # commits where both changed
+    degree: float  # shared / min(individual commit counts)
+
+
+def coupling(
+    commits: list[Commit],
+    stats: dict[str, FileStat],
+    limit: int = 20,
+    min_shared: int = 3,
+    max_files_per_commit: int = 30,
+) -> list[CouplingPair]:
+    """Pairs of files that tend to change together.
+
+    Commits touching a huge number of files (bulk reformat, vendoring) are
+    skipped so they don't drown real coupling in noise.
+    """
+    pair_counts: Counter = Counter()
+    file_commits: Counter = Counter()
+
+    for commit in commits:
+        paths = sorted({fc.path for fc in commit.files})
+        if len(paths) > max_files_per_commit:
+            continue
+        for path in paths:
+            file_commits[path] += 1
+        for i in range(len(paths)):
+            for j in range(i + 1, len(paths)):
+                pair_counts[(paths[i], paths[j])] += 1
+
+    results: list[CouplingPair] = []
+    for (a, b), shared in pair_counts.items():
+        if shared < min_shared:
+            continue
+        sa, sb = stats.get(a), stats.get(b)
+        if not sa or not sb or not sa.exists or not sb.exists:
+            continue
+        degree = shared / min(file_commits[a], file_commits[b])
+        results.append(CouplingPair(a=a, b=b, shared=shared, degree=degree))
+
+    results.sort(key=lambda p: (p.degree, p.shared), reverse=True)
+    return results[:limit]
+
+
+@dataclass
+class ChangedFileRisk:
+    path: str
+    risk: int  # 0-100
+    commits: int
+    loc: int
+    reasons: list[str]
+
+
+@dataclass
+class ReleaseRisk:
+    """Risk of shipping a specific set of changed files.
+
+    A release is treated as roughly as risky as its riskiest file, with the
+    count of high-risk files raising the overall level — this maps directly to
+    DORA's change-failure-rate concern.
+    """
+
+    files: list[ChangedFileRisk]
+    score: int  # 0-100, overall
+    level: str  # LOW | MEDIUM | HIGH
+    high_risk_count: int
+
+
+_HIGH, _MEDIUM = 70, 40
+
+
+def _level(score: int) -> str:
+    if score >= _HIGH:
+        return "HIGH"
+    if score >= _MEDIUM:
+        return "MEDIUM"
+    return "LOW"
+
+
+def release_risk(changed: list[str], stats: dict[str, FileStat]) -> ReleaseRisk:
+    """Score a set of changed paths against the repo's accumulated risk map."""
+    max_score = max((s.hotspot_score for s in stats.values() if s.exists), default=0)
+
+    files: list[ChangedFileRisk] = []
+    for path in changed:
+        stat = stats.get(path)
+        if stat is None or not stat.exists:
+            # New or untracked file: no history to judge it by.
+            files.append(ChangedFileRisk(path=path, risk=0, commits=0, loc=0, reasons=["nouveau / sans historique"]))
+            continue
+
+        risk = round(stat.hotspot_score / max_score * 100) if max_score else 0
+        reasons: list[str] = []
+        if risk >= _HIGH:
+            reasons.append("hotspot majeur")
+        elif risk >= _MEDIUM:
+            reasons.append("zone active")
+        if stat.commits >= 3 and stat.num_authors == 1:
+            owner = stat.main_owner[0]
+            reasons.append(f"auteur unique ({owner})")
+            risk = min(100, risk + 10)  # single-owner changes are riskier to review
+        files.append(ChangedFileRisk(path=path, risk=risk, commits=stat.commits, loc=stat.loc, reasons=reasons or ["—"]))
+
+    files.sort(key=lambda f: f.risk, reverse=True)
+    score = files[0].risk if files else 0
+    high = sum(1 for f in files if f.risk >= _HIGH)
+    # Several risky files in one release pushes the ceiling up a tier.
+    if high >= 2:
+        score = max(score, _HIGH)
+    return ReleaseRisk(files=files, score=score, level=_level(score), high_risk_count=high)
+
+
+@dataclass
+class Reviewer:
+    name: str
+    files_known: int  # how many of the changed files this person has touched
+    commits: int  # their total commits across those files
+
+
+def suggested_reviewers(changed: list[str], stats: dict[str, FileStat], limit: int = 3):
+    """Who knows the changed code best, from git history.
+
+    Returns (known_file_count, reviewers). Ranks by how many of the changed
+    files a person has touched, then by their commit depth on them — exactly
+    what you want when picking a reviewer for a PR.
+    """
+    known = [p for p in changed if p in stats and stats[p].exists and stats[p].authors]
+    commits_by_author: Counter = Counter()
+    files_by_author: dict[str, set] = defaultdict(set)
+    for path in known:
+        for author, n in stats[path].authors.items():
+            commits_by_author[author] += n
+            files_by_author[author].add(path)
+
+    reviewers = [
+        Reviewer(name=a, files_known=len(files_by_author[a]), commits=commits_by_author[a])
+        for a in commits_by_author
+    ]
+    reviewers.sort(key=lambda r: (r.files_known, r.commits), reverse=True)
+    return len(known), reviewers[:limit]
+
+
+@dataclass
+class StaleFile:
+    path: str
+    complexity: int
+    days_stale: int
+    main_owner: tuple
+
+
+def stale_risks(stats: dict[str, FileStat], now_ts: int, limit: int = 15) -> list[StaleFile]:
+    """Complex files nobody has touched in a long time.
+
+    Important logic that is quietly aging: still complex, but in the older half
+    of the repo's recency range — the kind of code that breaks when someone
+    finally has to change it and no one remembers how it works.
+    """
+    present = [s for s in stats.values() if s.exists and s.complexity > 1 and s.last_timestamp]
+    if len(present) < 4:
+        return []
+    comps = sorted(s.complexity for s in present)
+    median_cx = comps[len(comps) // 2]
+    max_days = max((now_ts - s.last_timestamp) for s in present) / 86400 or 1
+
+    out: list[StaleFile] = []
+    for s in present:
+        days = (now_ts - s.last_timestamp) / 86400
+        if s.complexity >= median_cx and days >= max_days * 0.5:
+            out.append(StaleFile(s.path, s.complexity, int(days), s.main_owner))
+    out.sort(key=lambda f: f.complexity * (f.days_stale + 1), reverse=True)
+    return out[:limit]
+
+
+@dataclass
+class Health:
+    score: int
+    grade: str  # A..F
+    color: str  # shields.io colour name
+    reasons: list[str]
+
+
+def health_grade(stats: dict[str, FileStat], summary, trend) -> Health:
+    """A single A–F health grade, from transparent penalties."""
+    score = 100
+    reasons: list[str] = []
+
+    active = summary.active_files or 1
+    bus = bus_factor_risks(stats, limit=10 ** 9)
+    pen_bus = min(30, round(len(bus) / active * 100))
+    if pen_bus:
+        score -= pen_bus
+        reasons.append(f"-{pen_bus} bus factor ({len(bus)} fichiers à auteur unique)")
+
+    if trend and trend.direction == "up":
+        score -= 15
+        reasons.append("-15 pression hotspots en hausse")
+    elif trend and trend.direction == "down":
+        score = min(100, score + 5)
+        reasons.append("+5 pression hotspots en baisse")
+
+    score = max(0, min(100, score))
+    grade = ("A" if score >= 85 else "B" if score >= 70 else "C" if score >= 55
+             else "D" if score >= 40 else "F")
+    color = {"A": "brightgreen", "B": "green", "C": "yellow", "D": "orange", "F": "red"}[grade]
+    return Health(score=score, grade=grade, color=color, reasons=reasons)
+
+
+def find_files(stats: dict[str, FileStat], query: str) -> list[str]:
+    """Resolve a user-typed path to tracked file paths (exact, then suffix/basename)."""
+    q = query.replace("\\", "/").lstrip("./").lower()
+    if query in stats:
+        return [query]
+    exact = [p for p in stats if p.lower() == q]
+    if exact:
+        return exact
+    return sorted(p for p in stats if p.lower().endswith("/" + q) or p.split("/")[-1].lower() == q)
+
+
+@dataclass
+class Summary:
+    total_commits: int
+    tracked_files: int
+    active_files: int  # still present on disk
+    contributors: int
+    first_timestamp: int
+    last_timestamp: int
+    top_contributors: list[tuple[str, int]]
+
+
+@dataclass
+class TrendBucket:
+    label: str  # bucket key (day, week, or month depending on span)
+    commits: int = 0
+    added: int = 0
+    deleted: int = 0
+    hotspot_commits: int = 0  # commits in this month touching a top hotspot
+    cum_net: int = 0  # cumulative (added - deleted) up to this month
+
+    @property
+    def churn(self) -> int:
+        return self.added + self.deleted
+
+    @property
+    def hotspot_pct(self) -> float:
+        return self.hotspot_commits / self.commits if self.commits else 0.0
+
+
+@dataclass
+class Trend:
+    buckets: list[TrendBucket]
+    verdict: str  # human sentence: is hotspot pressure rising or falling?
+    direction: str  # "up" | "down" | "flat"
+    granularity: str  # "jour" | "semaine" | "mois"
+
+
+def _bucket_key(span_days: float):
+    """Pick day/week/month buckets so short and long histories both read well."""
+    if span_days <= 31:
+        return "jour", lambda ts: _dt.datetime.fromtimestamp(ts).strftime("%m-%d")
+    if span_days <= 180:
+        return "semaine", lambda ts: _dt.datetime.fromtimestamp(ts).strftime("%Y-W%V")
+    return "mois", lambda ts: _dt.datetime.fromtimestamp(ts).strftime("%Y-%m")
+
+
+def monthly_trend(commits: list[Commit], hotspot_paths: set[str], max_buckets: int = 24) -> Trend:
+    """Bucket history over time (granularity auto-picked) and track activity,
+    code size and hotspot pressure."""
+    timestamps = [c.timestamp for c in commits] or [0]
+    span_days = (max(timestamps) - min(timestamps)) / 86400
+    granularity, keyfn = _bucket_key(span_days)
+
+    buckets: dict[str, TrendBucket] = defaultdict(lambda: TrendBucket(label=""))
+    for c in commits:
+        key = keyfn(c.timestamp)
+        b = buckets[key]
+        b.label = key
+        b.commits += 1
+        touched_hot = False
+        for fc in c.files:
+            b.added += fc.added
+            b.deleted += fc.deleted
+            if fc.path in hotspot_paths:
+                touched_hot = True
+        if touched_hot:
+            b.hotspot_commits += 1
+
+    ordered = [buckets[k] for k in sorted(buckets)]
+    running = 0
+    for b in ordered:
+        running += b.added - b.deleted
+        b.cum_net = running
+    ordered = ordered[-max_buckets:]
+
+    direction, verdict = _hotspot_pressure_trend(ordered)
+    return Trend(buckets=ordered, verdict=verdict, direction=direction, granularity=granularity)
+
+
+def _hotspot_pressure_trend(buckets: list[TrendBucket]) -> tuple[str, str]:
+    """Compare recent hotspot pressure to earlier, as a debt signal."""
+    active = [b for b in buckets if b.commits > 0]
+    if len(active) < 4:
+        return "flat", "Pas assez d'historique pour dégager une tendance."
+    half = len(active) // 2
+    early = sum(b.hotspot_pct for b in active[:half]) / half
+    late = sum(b.hotspot_pct for b in active[half:]) / (len(active) - half)
+    delta = late - early
+    if delta > 0.08:
+        return "up", f"⚠️ La pression sur les hotspots augmente ({round(early*100)}% → {round(late*100)}% des commits). La dette se concentre."
+    if delta < -0.08:
+        return "down", f"✅ La pression sur les hotspots diminue ({round(early*100)}% → {round(late*100)}% des commits). Bon signe."
+    return "flat", f"La pression sur les hotspots est stable (~{round(late*100)}% des commits)."
+
+
+def summarize(commits: list[Commit], stats: dict[str, FileStat]) -> Summary:
+    author_commits: Counter = Counter(c.author for c in commits)
+    timestamps = [c.timestamp for c in commits] or [0]
+    return Summary(
+        total_commits=len(commits),
+        tracked_files=len(stats),
+        active_files=sum(1 for s in stats.values() if s.exists),
+        contributors=len(author_commits),
+        first_timestamp=min(timestamps),
+        last_timestamp=max(timestamps),
+        top_contributors=author_commits.most_common(8),
+    )

codepulse/charts.py

@@ -0,0 +1,126 @@
+"""Tiny dependency-free SVG charts for the trend section.
+
+One series per chart (small multiples), never a dual axis. Marks are thin, axes
+recessive, bar ends rounded, x-labels selective (first/last), and every mark
+carries a native <title> tooltip. Colours come from the report's CSS tokens so
+light/dark both work.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+# viewBox geometry (unitless; the SVG scales to its container via width:100%).
+_W, _H = 360, 180
+_L, _R, _T, _B = 8, 10, 14, 24
+_PLOT_W = _W - _L - _R
+_PLOT_H = _H - _T - _B
+_BASE = _T + _PLOT_H  # baseline y
+
+
+def _frame(title: str, body: str, ymax_label: str) -> str:
+    return f"""<figure class="chart">
+  <figcaption>{title}</figcaption>
+  <svg viewBox="0 0 {_W} {_H}" role="img" preserveAspectRatio="xMidYMid meet">
+    <line class="axis" x1="{_L}" y1="{_BASE}" x2="{_W - _R}" y2="{_BASE}"/>
+    <text class="ymax" x="{_L}" y="{_T - 3}">{ymax_label}</text>
+    {body}
+  </svg>
+</figure>"""
+
+
+def _xlabels(labels: list[str], xs: list[float]) -> str:
+    if not labels:
+        return ""
+    parts = [f'<text class="xlab" x="{xs[0]:.1f}" y="{_BASE + 15}" text-anchor="start">{labels[0]}</text>']
+    if len(labels) > 1:
+        parts.append(f'<text class="xlab" x="{xs[-1]:.1f}" y="{_BASE + 15}" text-anchor="end">{labels[-1]}</text>')
+    return "\n    ".join(parts)
+
+
+def bars(title: str, data: list[tuple[str, float]], cls: str, fmt: Callable[[float], str]) -> str:
+    if not data:
+        return _frame(title, '<text class="empty-svg" x="180" y="90" text-anchor="middle">pas de données</text>', "")
+    labels = [d[0] for d in data]
+    values = [d[1] for d in data]
+    vmax = max(values) or 1
+    n = len(data)
+    slot = _PLOT_W / n
+    bw = min(slot * 0.68, 26)
+    rects, xs = [], []
+    for i, (label, v) in enumerate(data):
+        x = _L + i * slot + (slot - bw) / 2
+        xs.append(x + bw / 2)
+        h = (v / vmax) * _PLOT_H
+        y = _BASE - h
+        r = min(3, bw / 2)
+        if h <= r:
+            path = f'M{x:.1f},{_BASE} h{bw:.1f} V{y:.1f} h{-bw:.1f} Z'
+        else:
+            path = (f'M{x:.1f},{_BASE} V{y + r:.1f} q0,{-r} {r},{-r} '
+                    f'h{bw - 2 * r:.1f} q{r},0 {r},{r} V{_BASE} Z')
+        rects.append(f'<path class="mark {cls}" d="{path}"><title>{label}: {fmt(v)}</title></path>')
+    body = "\n    ".join(rects) + "\n    " + _xlabels(labels, xs)
+    return _frame(title, body, fmt(vmax))
+
+
+def line(title: str, data: list[tuple[str, float]], cls: str, fmt: Callable[[float], str], area: bool = True) -> str:
+    if not data:
+        return _frame(title, '<text class="empty-svg" x="180" y="90" text-anchor="middle">pas de données</text>', "")
+    labels = [d[0] for d in data]
+    values = [d[1] for d in data]
+    vmax = max(values) or 1
+    vmin = min(values)
+    span = (vmax - vmin) or 1
+    n = len(data)
+    xs = [_L + (i / (n - 1) * _PLOT_W if n > 1 else _PLOT_W / 2) for i in range(n)]
+    ys = [_BASE - ((v - vmin) / span) * _PLOT_H for v in values]
+    pts = " ".join(f"{x:.1f},{y:.1f}" for x, y in zip(xs, ys))
+
+    body = []
+    if area:
+        body.append(f'<polygon class="area {cls}" points="{xs[0]:.1f},{_BASE} {pts} {xs[-1]:.1f},{_BASE}"/>')
+    body.append(f'<polyline class="line {cls}" points="{pts}"/>')
+    # Transparent hit targets so every point has a hover tooltip.
+    for (x, y), label, v in zip(zip(xs, ys), labels, values):
+        body.append(f'<circle class="hit" cx="{x:.1f}" cy="{y:.1f}" r="7"><title>{label}: {fmt(v)}</title></circle>')
+    body.append(f'<circle class="dot {cls}" cx="{xs[-1]:.1f}" cy="{ys[-1]:.1f}" r="3"/>')
+    body.append(_xlabels(labels, xs))
+    return _frame(title, "\n    ".join(body), fmt(vmax))
+
+
+# Formatters ---------------------------------------------------------------
+
+def fmt_int(v: float) -> str:
+    return f"{int(round(v)):,}"
+
+
+def fmt_pct(v: float) -> str:
+    return f"{round(v * 100)}%"
+
+
+CHART_CSS = """
+.trend-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }
+@media (max-width: 680px) { .trend-grid { grid-template-columns: 1fr; } }
+.chart { margin: 0; }
+.chart figcaption { font-size: 12px; color: var(--muted); margin-bottom: 4px; font-weight: 600; }
+.chart svg { width: 100%; height: auto; display: block; }
+.chart .axis { stroke: var(--line); stroke-width: 1; }
+.chart .ymax { fill: var(--muted); font-size: 10px; font-variant-numeric: tabular-nums; }
+.chart .xlab { fill: var(--muted); font-size: 10px; }
+.chart .empty-svg { fill: var(--muted); font-size: 12px; }
+.chart .mark.accent { fill: var(--accent); }
+.chart .mark.hot { fill: var(--hot); }
+.chart .mark { transition: opacity .1s; }
+.chart .mark:hover { opacity: .75; }
+.chart .line { fill: none; stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; }
+.chart .line.accent { stroke: var(--accent); }
+.chart .line.hot { stroke: var(--hot); }
+.chart .area.accent { fill: var(--accent); opacity: .12; }
+.chart .area.hot { fill: var(--hot); opacity: .12; }
+.chart .dot.accent { fill: var(--accent); }
+.chart .dot.hot { fill: var(--hot); }
+.chart .hit { fill: transparent; }
+.verdict { font-size: 14px; margin: 0 0 16px; padding: 10px 14px; border-radius: 10px;
+  background: var(--bg); border: 1px solid var(--line); }
+"""