codepulse-cli 0.1.0__tar.gz → 0.1.3__tar.gz

codepulse_cli-0.1.3/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: publish
+
+# Builds and publishes to PyPI whenever a GitHub release is published.
+# Uses PyPI Trusted Publishing (OIDC) — no API token stored anywhere.
+# Remember to bump `version` in pyproject.toml before creating the release.
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # required for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build distributions
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

{codepulse_cli-0.1.0 → codepulse_cli-0.1.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codepulse-cli
-Version: 0.1.0
+Version: 0.1.3
 Summary: Reveal a codebase's health from its git history — hotspots, bus factor, hidden coupling, and a CI risk gate.
 Project-URL: Homepage, https://github.com/Mehouelley/codepulse
 Project-URL: Repository, https://github.com/Mehouelley/codepulse
@@ -45,31 +45,22 @@ with **zero dependencies** beyond git and Python.
 
 ## Demo
 
-<!-- Render docs/demo.gif from demo.tape with `vhs demo.tape`, then:
-     ![demo](docs/demo.gif) -->
+![CodePulse demo](docs/demo.gif)
 
 ```console
 $ codepulse . --badge
 Grade: B (83/100)
-  -2 bus factor (9 fichiers à auteur unique)
-  -15 pression hotspots en hausse
-![code health](https://img.shields.io/badge/code%20health-B%20(83)-green)
 
 $ codepulse . --changed origin/main
-🔴 Release risk: HIGH (100/100)
-   56 changed files · 2 high-risk
-   [100] crates/ui-egui/src/lib.rs  (hotspot majeur)
-   [ 70] crates/layout/src/para.rs  (zone active, auteur unique)
-   👥 Relecteurs suggérés: Valentin Klein (29/37 fichiers), Dmitrii Khlapov (22/37)
+Release risk: HIGH (100/100)
+   [100] crates/ui-egui/src/lib.rs   (major hotspot)
+   Reviewers: Valentin Klein (29/37), Dmitrii Khlapov (22/37)
 
 $ codepulse . --who crates/ui-egui/src/canvas.rs
-crates/ui-egui/src/canvas.rs — 64 commits, 22 auteur(s), dernier changement 2026-10-12
-   45%   29 commits  Valentin Klein
-   11%    7 commits  Dmitrii Khlapov
+canvas.rs — 64 commits, 22 authors — 45% Valentin Klein
 ```
 
-> A recordable [`demo.tape`](demo.tape) (for [VHS](https://github.com/charmbracelet/vhs))
-> generates an animated `docs/demo.gif` of the above.
+> The GIF is generated from [`demo.tape`](demo.tape) ([VHS](https://github.com/charmbracelet/vhs)).
 
 ---
 
@@ -87,18 +78,24 @@ or email to your team.
 
 ---
 
+## Install
+
+```bash
+pip install codepulse-cli    # installs the `codepulse` command
+```
+
 ## Quick start
 
 ```bash
 # From a git repository:
-python -m codepulse /path/to/repo --open
+codepulse /path/to/repo --open
 
 # Common options:
-python -m codepulse . --since "6 months ago" --top 30 -o health.html
+codepulse . --since "6 months ago" --top 30 -o health.html
 ```
 
-> Running from the source checkout? Prefix with `PYTHONPATH=src`, or install it:
-> `pip install -e .` then just run `codepulse`.
+> Running from a source checkout instead? Use `python -m codepulse` with
+> `PYTHONPATH=src`, or `pip install -e .`.
 
 ### Options
 
@@ -211,6 +208,7 @@ simple enough to run in one command.
 - [x] `--who <file>` — who knows this code best
 - [x] `--badge` — shareable A–F health badge for your README
 - [x] Orphaned-code section — complex files nobody touches anymore
+- [x] **Recommendations** — prioritized, concrete actions, not just findings
 
 ## Development
 

{codepulse_cli-0.1.0 → codepulse_cli-0.1.3}/README.md

@@ -19,31 +19,22 @@ with **zero dependencies** beyond git and Python.
 
 ## Demo
 
-<!-- Render docs/demo.gif from demo.tape with `vhs demo.tape`, then:
-     ![demo](docs/demo.gif) -->
+![CodePulse demo](docs/demo.gif)
 
 ```console
 $ codepulse . --badge
 Grade: B (83/100)
-  -2 bus factor (9 fichiers à auteur unique)
-  -15 pression hotspots en hausse
-![code health](https://img.shields.io/badge/code%20health-B%20(83)-green)
 
 $ codepulse . --changed origin/main
-🔴 Release risk: HIGH (100/100)
-   56 changed files · 2 high-risk
-   [100] crates/ui-egui/src/lib.rs  (hotspot majeur)
-   [ 70] crates/layout/src/para.rs  (zone active, auteur unique)
-   👥 Relecteurs suggérés: Valentin Klein (29/37 fichiers), Dmitrii Khlapov (22/37)
+Release risk: HIGH (100/100)
+   [100] crates/ui-egui/src/lib.rs   (major hotspot)
+   Reviewers: Valentin Klein (29/37), Dmitrii Khlapov (22/37)
 
 $ codepulse . --who crates/ui-egui/src/canvas.rs
-crates/ui-egui/src/canvas.rs — 64 commits, 22 auteur(s), dernier changement 2026-10-12
-   45%   29 commits  Valentin Klein
-   11%    7 commits  Dmitrii Khlapov
+canvas.rs — 64 commits, 22 authors — 45% Valentin Klein
 ```
 
-> A recordable [`demo.tape`](demo.tape) (for [VHS](https://github.com/charmbracelet/vhs))
-> generates an animated `docs/demo.gif` of the above.
+> The GIF is generated from [`demo.tape`](demo.tape) ([VHS](https://github.com/charmbracelet/vhs)).
 
 ---
 
@@ -61,18 +52,24 @@ or email to your team.
 
 ---
 
+## Install
+
+```bash
+pip install codepulse-cli    # installs the `codepulse` command
+```
+
 ## Quick start
 
 ```bash
 # From a git repository:
-python -m codepulse /path/to/repo --open
+codepulse /path/to/repo --open
 
 # Common options:
-python -m codepulse . --since "6 months ago" --top 30 -o health.html
+codepulse . --since "6 months ago" --top 30 -o health.html
 ```
 
-> Running from the source checkout? Prefix with `PYTHONPATH=src`, or install it:
-> `pip install -e .` then just run `codepulse`.
+> Running from a source checkout instead? Use `python -m codepulse` with
+> `PYTHONPATH=src`, or `pip install -e .`.
 
 ### Options
 
@@ -185,6 +182,7 @@ simple enough to run in one command.
 - [x] `--who <file>` — who knows this code best
 - [x] `--badge` — shareable A–F health badge for your README
 - [x] Orphaned-code section — complex files nobody touches anymore
+- [x] **Recommendations** — prioritized, concrete actions, not just findings
 
 ## Development
 

{codepulse_cli-0.1.0 → codepulse_cli-0.1.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codepulse-cli"
-version = "0.1.0"
+version = "0.1.3"
 description = "Reveal a codebase's health from its git history — hotspots, bus factor, hidden coupling, and a CI risk gate."
 readme = "README.md"
 requires-python = ">=3.10"

{codepulse_cli-0.1.0 → codepulse_cli-0.1.3}/src/codepulse/__init__.py

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

{codepulse_cli-0.1.0 → codepulse_cli-0.1.3}/src/codepulse/analyzers.py

@@ -314,6 +314,86 @@ def stale_risks(stats: dict[str, FileStat], now_ts: int, limit: int = 15) -> lis
     return out[:limit]
 
 
+@dataclass
+class Recommendation:
+    priority: int  # 1 = most urgent
+    icon: str
+    title: str
+    action: str
+
+
+def _duplicate_authors(commits: list[Commit]) -> list[tuple[str, ...]]:
+    """Author names that differ only by case/spacing — likely one person."""
+    groups: dict[str, set] = defaultdict(set)
+    for c in commits:
+        groups[c.author.strip().lower()].add(c.author.strip())
+    return [tuple(sorted(v)) for v in groups.values() if len(v) > 1]
+
+
+def recommendations(
+    commits: list[Commit],
+    hotspots: list[FileStat],
+    bus_risks: list[FileStat],
+    coupling: list[CouplingPair],
+    trend,
+    stale: list[StaleFile],
+    limit: int = 8,
+) -> list[Recommendation]:
+    """Turn the findings into concrete, prioritized actions to take."""
+    recs: list[Recommendation] = []
+
+    for h in hotspots[:2]:
+        recs.append(Recommendation(
+            1, "🔥", f"Refactorer `{h.path}`",
+            f"{h.commits} commits et une complexité de {h.complexity} : c'est un point chaud majeur, "
+            f"là où les bugs naissent. Découpez-le en unités plus petites et couvrez-le de tests avant d'y retoucher.",
+        ))
+
+    if trend and trend.direction == "up":
+        recs.append(Recommendation(
+            1, "📈", "Freiner la dette technique",
+            "La part des commits touchant les hotspots augmente. Gelez les nouvelles fonctionnalités sur ces "
+            "fichiers et refactorez-les d'abord, sinon les bugs vont s'accumuler.",
+        ))
+
+    if bus_risks:
+        top = bus_risks[0]
+        owner = top.main_owner[0] or "une seule personne"
+        recs.append(Recommendation(
+            2, "👥", "Partager la connaissance",
+            f"{len(bus_risks)} fichiers n'ont qu'un seul auteur (ex. `{top.path}`, par {owner}). "
+            "Documentez-les ou passez-les en revue à deux : si cette personne part, ce savoir disparaît.",
+        ))
+
+    dupes = _duplicate_authors(commits)
+    if dupes:
+        a, b = dupes[0][0], dupes[0][1]
+        recs.append(Recommendation(
+            2, "🪪", "Unifier les identités git",
+            f"« {a} » et « {b} » semblent être la même personne (casse différente). Ajoutez un fichier "
+            "`.mailmap` pour fusionner les statistiques et compter les contributeurs correctement.",
+        ))
+
+    if coupling:
+        p = coupling[0]
+        recs.append(Recommendation(
+            3, "🔗", "Clarifier un couplage caché",
+            f"`{p.a}` et `{p.b}` changent presque toujours ensemble ({p.shared}×). Vérifiez cette dépendance : "
+            "à expliciter, documenter, ou factoriser si elle est accidentelle.",
+        ))
+
+    if stale:
+        s = stale[0]
+        recs.append(Recommendation(
+            3, "🕸️", "Revoir du code qui vieillit",
+            f"`{s.path}` est complexe (complexité {s.complexity}) mais intact depuis {s.days_stale} jours. "
+            "Vérifiez qu'il est encore utile, à jour et documenté avant que personne ne s'en souvienne.",
+        ))
+
+    recs.sort(key=lambda r: r.priority)
+    return recs[:limit]
+
+
 @dataclass
 class Health:
     score: int

{codepulse_cli-0.1.0 → codepulse_cli-0.1.3}/src/codepulse/cli.py

@@ -71,21 +71,33 @@ def _run_report(repo: str, args: argparse.Namespace) -> int:
     stats = analyzers.build_file_stats(commits, repo)
     summary = analyzers.summarize(commits, stats)
     hot = analyzers.hotspots(stats, limit=args.top)
+    bus = analyzers.bus_factor_risks(stats, limit=args.top)
     hotspot_paths = {h.path for h in analyzers.hotspots(stats, limit=15)}
+    trend = analyzers.monthly_trend(commits, hotspot_paths)
+    coupled = analyzers.coupling(commits, stats, limit=args.top)
+    stale = analyzers.stale_risks(stats, summary.last_timestamp, limit=args.top)
+    recs = analyzers.recommendations(commits, hot, bus, coupled, trend, stale)
+
     html = render(
         repo_name=os.path.basename(repo.rstrip("/\\")) or repo,
         summary=summary,
         hotspots=hot,
-        bus_risks=analyzers.bus_factor_risks(stats, limit=args.top),
-        coupling=analyzers.coupling(commits, stats, limit=args.top),
-        trend=analyzers.monthly_trend(commits, hotspot_paths),
-        stale=analyzers.stale_risks(stats, summary.last_timestamp, limit=args.top),
+        bus_risks=bus,
+        coupling=coupled,
+        trend=trend,
+        stale=stale,
+        recommendations=recs,
     )
 
     out = os.path.abspath(args.output)
     with open(out, "w", encoding="utf-8") as fh:
         fh.write(html)
     print(f"\nReport written to {out}")
+    if recs:
+        print("\nRecommandations :")
+        for i, r in enumerate(recs, 1):
+            print(f"  {i}. {r.icon} {r.title.replace('`', '')}")
+            print(f"     {r.action.replace('`', '')}")
     if args.open:
         webbrowser.open(f"file://{out}")
     return 0

{codepulse_cli-0.1.0 → codepulse_cli-0.1.3}/src/codepulse/report.py

@@ -10,7 +10,7 @@ import datetime as _dt
 import html
 
 from . import charts
-from .analyzers import CouplingPair, FileStat, StaleFile, Summary, Trend
+from .analyzers import CouplingPair, FileStat, Recommendation, StaleFile, Summary, Trend
 
 
 def _esc(value: object) -> str:
@@ -79,6 +79,32 @@ def _stale_section(stale: list[StaleFile]) -> str:
   </section>"""
 
 
+def _code_spans(text: str) -> str:
+    """Escape, then turn `backtick` spans into <code>."""
+    out, code = [], False
+    for part in _esc(text).split("`"):
+        out.append(f"<code>{part}</code>" if code else part)
+        code = not code
+    return "".join(out)
+
+
+def _rec_section(recs: list[Recommendation]) -> str:
+    if not recs:
+        return ""
+    items = "\n".join(
+        f"""<li class="rec p{min(r.priority, 3)}">
+          <div class="rec-head">{r.icon} <strong>{_esc(r.title)}</strong></div>
+          <div class="rec-action">{_code_spans(r.action)}</div>
+        </li>"""
+        for r in recs
+    )
+    return f"""<section class="recs-section">
+    <h2>🎯 Recommandations</h2>
+    <p class="hint">Les actions concrètes à prendre, de la plus urgente à la moins urgente.</p>
+    <ol class="recs">{items}</ol>
+  </section>"""
+
+
 def render(
     repo_name: str,
     summary: Summary,
@@ -87,6 +113,7 @@ def render(
     coupling: list[CouplingPair],
     trend: Trend | None = None,
     stale: list[StaleFile] | None = None,
+    recommendations: list[Recommendation] | None = None,
 ) -> str:
     generated = _dt.datetime.now().strftime("%Y-%m-%d %H:%M")
     span = f"{_date(summary.first_timestamp)} → {_date(summary.last_timestamp)}"
@@ -136,6 +163,7 @@ def render(
         generated=generated,
         span=span,
         chart_css=charts.CHART_CSS,
+        rec_section=_rec_section(recommendations or []),
         trend_section=_trend_section(trend),
         stale_section=_stale_section(stale or []),
         total_commits=f"{summary.total_commits:,}",
@@ -207,6 +235,23 @@ tr:last-child td {{ border-bottom: none; }}
 .badge.mid {{ background: var(--mid); }}
 .badge.low {{ background: var(--low); }}
 .empty {{ color: var(--muted); text-align: center; padding: 20px; }}
+.recs-section {{ border-color: var(--accent); }}
+ol.recs {{ list-style: none; counter-reset: rec; margin: 0; padding: 0; }}
+ol.recs .rec {{ counter-increment: rec; position: relative; padding: 12px 12px 12px 44px; margin-bottom: 10px;
+  border: 1px solid var(--line); border-left: 4px solid var(--muted); border-radius: 10px; background: var(--bg); }}
+ol.recs .rec::before {{ content: counter(rec); position: absolute; left: 12px; top: 12px; width: 22px; height: 22px;
+  border-radius: 50%; background: var(--muted); color: #fff; font-size: 12px; font-weight: 700;
+  display: flex; align-items: center; justify-content: center; }}
+ol.recs .rec.p1 {{ border-left-color: var(--hot); }}
+ol.recs .rec.p1::before {{ background: var(--hot); }}
+ol.recs .rec.p2 {{ border-left-color: var(--mid); }}
+ol.recs .rec.p2::before {{ background: var(--mid); }}
+ol.recs .rec.p3 {{ border-left-color: var(--low); }}
+ol.recs .rec.p3::before {{ background: var(--low); }}
+.rec-head {{ font-size: 15px; margin-bottom: 3px; }}
+.rec-action {{ color: var(--muted); font-size: 14px; }}
+.rec-action code {{ font-family: ui-monospace, Consolas, monospace; font-size: 12px; color: var(--ink);
+  background: var(--panel); padding: 1px 5px; border-radius: 4px; border: 1px solid var(--line); }}
 ul.contrib {{ list-style: none; margin: 0; padding: 0; }}
 ul.contrib li {{ display: grid; grid-template-columns: 180px 1fr 40px; gap: 10px; align-items: center; padding: 5px 0; }}
 ul.contrib .c-name {{ font-size: 14px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }}
@@ -232,6 +277,8 @@ footer a {{ color: var(--accent); text-decoration: none; }}
     <div class="card"><div class="k">Contributeurs</div><div class="v">{contributors}</div></div>
   </div>
 
+  {rec_section}
+
   {trend_section}
 
   <section>

{codepulse_cli-0.1.0 → codepulse_cli-0.1.3}/tests/test_analyzers.py

@@ -90,6 +90,21 @@ def test_release_risk_high_for_hotspot_single_owner():
     assert any("auteur unique" in r for r in risk.files[0].reasons)
 
 
+def test_recommendations_prioritize_and_detect_duplicate_authors():
+    commits = [
+        Commit(str(i), i * DAY, "Alice" if i % 2 else "alice",
+               files=[FileChange("hot.py", 1, 0)])
+        for i in range(6)
+    ]
+    hot = [stat("hot.py", commits=6, authors={"Alice": 3, "alice": 3}, complexity=40)]
+    bus = [stat("solo.py", commits=4, authors={"Alice": 4})]
+    recs = analyzers.recommendations(commits, hot, bus, [], None, [])
+    titles = " ".join(r.title for r in recs)
+    assert "hot.py" in titles  # top hotspot recommended
+    assert any("identit" in r.title.lower() for r in recs)  # duplicate Alice/alice detected
+    assert recs == sorted(recs, key=lambda r: r.priority)  # sorted by urgency
+
+
 def test_suggested_reviewers_ranks_by_coverage_then_depth():
     stats = {
         "a.py": stat("a.py", 5, {"Alice": 4, "Bob": 1}),