fix(growth-report): implement PR #26 review findings (dsblank)

- #1 workspace_active_series: report real per-bucket active totals
  instead of a flat total repeated across the series.
- #2 barsLine/lines: add right-axis scale (rAxis) for the secondary
  rate series and wire hover tooltips (attachTip) with per-column
  labels; remove dead indexOfKey/keyInRange JS helpers.
- #4 service accounts: drop the 'users' container key and match a
  service account by username OR email (mirror-failure safe).
- #5 workspace-growth KPI: surface the membership-proxy basis in the
  KPI sub ("+N new (est. from earliest member)").
- #6 scoping: add a caveat that per-user totals stay org-wide when
  workspaces are scoped.
- #7 lint/misc: fix Python E501s + stale docstrings; warn on growth
  series bucket truncation; pass reportMonth as a URL-encoded query
  param (and stop migrate_users' client dropping params); make _num
  rounding consistent; drop 7 dead window_start/window_end chart keys.
- tests: render coverage for barsLine, groupedBarsH, and that the
  leaderboards / personal-vs-service sections reach the rendered body.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: LeoRoccoBreedt

cometx/cli/admin.py

@@ -464,7 +464,9 @@ def get_parser_arguments(parser):
     )
 
     # growth-report subcommand
-    growth_report_description = """Generate a cross-platform use-case growth report for one or more workspaces.
+    growth_report_description = """\
+Generate an org-wide people/usage growth report from the admin \
+chargeback report.
 
 Arguments:
     WORKSPACE (optional, one or more)
@@ -488,7 +490,10 @@ def get_parser_arguments(parser):
 """
     growth_parser = subparsers.add_parser(
         "growth-report",
-        help="Generate a cross-platform use-case growth report for one or more workspaces",
+        help=(
+            "Generate an org-wide people/usage growth report from the "
+            "admin chargeback report"
+        ),
         description=growth_report_description,
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )

cometx/cli/admin_growth_render.py

@@ -21,11 +21,11 @@
 calls, no secrets -- `report_data` never carries an API key.
 
 Charts render as plain month-on-month / week-on-week series with horizontal
-gridlines for scale. The earlier single-analysis-window overlay (a shaded
-`[window_start, window_end]` band with accent-vs-muted fill and start/end
-dots) has been removed now that the report is period-over-period; the
-`window_start`/`window_end` fields in chart data are retained but no longer
-drawn. A window chip is still rendered next to each section title.
+gridlines for scale. An earlier single-analysis-window overlay (a shaded
+band with start/end dots) was removed once the report became
+period-over-period; the now-defunct `window_start`/`window_end` chart-data
+fields were dropped with it. A window chip is still rendered next to each
+section title.
 """
 
 from __future__ import annotations
@@ -207,17 +207,6 @@ def _fmt(value) -> str:
     return node;
   }
   function fmt(n){ return (n || 0).toLocaleString("en-US"); }
-  function indexOfKey(points, key){
-    if(key === undefined || key === null) return -1;
-    for(var i = 0; i < points.length; i++){ if(points[i].key === key) return i; }
-    return -1;
-  }
-  function keyInRange(key, start, end){
-    if(key === undefined || key === null) return false;
-    if(start !== undefined && start !== null && key < start) return false;
-    if(end !== undefined && end !== null && key > end) return false;
-    return true;
-  }
 
   var W = 560, H = 220, P = {t: 16, r: 14, b: 28, l: 44};
 
@@ -232,7 +221,7 @@ def _fmt(value) -> str:
     var guide = el("line", {class: "guide", y1: P.t, y2: H - P.b, x1: 0, x2: 0, opacity: "0"});
     svg.appendChild(guide);
     function show(col){
-      tip.textContent = col.key + ": " + fmt(col.value);
+      tip.textContent = col.label || (col.key + ": " + fmt(col.value));
       tip.classList.add("show");
       var r = host.getBoundingClientRect();
       tip.style.left = (col.x / W) * r.width + "px";
@@ -261,10 +250,22 @@ def _fmt(value) -> str:
     }
   }
 
+  // Right-hand axis ticks (unlabelled gridlines omitted; the left axis owns
+  // the grid) for a secondary series drawn on its own scale. `suffix` labels
+  // the units, e.g. "%". Colored to match the series it measures.
+  function rAxis(svg, yOf, maxVal, iw, suffix, color){
+    for(var g = 1; g <= 4; g++){
+      var v = maxVal * g / 4, y = yOf(v);
+      var t = el("text", {x: P.l + iw + 6, y: y + 3, "text-anchor": "start",
+        fill: color || tok("--muted"), "font-size": "10", "font-family": "var(--mono)"});
+      t.textContent = fmt(Math.round(v)) + (suffix || ""); svg.appendChild(t);
+    }
+  }
+
   function drawBars(host, data){
     data = data || {}; var points = data.points || [];
     if(!points.length){ host.innerHTML = "<p class=\\"nodata\\">No data</p>"; return; }
-    var accent = tok("--accent"), mute = tok("--bar-mute"), band = tok("--accent-soft");
+    var accent = tok("--accent");
     var svg = el("svg", {viewBox: "0 0 " + W + " " + H, role: "img"});
     var iw = W - P.l - P.r, ih = H - P.t - P.b, n = points.length;
     var max = 1; points.forEach(function(p){ max = Math.max(max, p.value || 0); });
@@ -290,7 +291,6 @@ def _fmt(value) -> str:
     data = data || {}; var points = data.points || []; var cats = data.categories || [];
     if(!points.length || !cats.length){ host.innerHTML = "<p class=\\"nodata\\">No data</p>"; return; }
     var colors = (data.colors && data.colors.length) ? data.colors : ["--accent", "--sdk", "--ok", "--warn"];
-    var accent = tok("--accent"), band = tok("--accent-soft");
     var svg = el("svg", {viewBox: "0 0 " + W + " " + H, role: "img"});
     var iw = W - P.l - P.r, ih = H - P.t - P.b, n = points.length;
     var max = 1;
@@ -321,6 +321,16 @@ def _fmt(value) -> str:
         fill: tok("--muted"), "font-size": "10", "font-family": "var(--mono)"});
       xl.textContent = points[i].key; svg.appendChild(xl);
     });
+    // Per-x tooltips: one column spanning the gap around each point, listing
+    // every category's value at that x.
+    var labels = data.labels || {};
+    var slot = n > 1 ? iw / (n - 1) : iw;
+    var cols = points.map(function(p, i){
+      var parts = [p.key];
+      cats.forEach(function(c){ parts.push((labels[c] || c) + " " + fmt((p.values && p.values[c]) || 0)); });
+      return {x: X(i), x0: X(i) - slot / 2, w: slot, key: p.key, label: parts.join("  \\u00b7  ")};
+    });
+    attachTip(host, svg, cols);
     host.appendChild(svg);
   }
 
@@ -373,8 +383,13 @@ def _fmt(value) -> str:
     if(!points.length || !bars.length){ host.innerHTML = "<p class=\\"nodata\\">No data</p>"; return; }
     var barColors = (data.bar_colors && data.bar_colors.length) ? data.bar_colors : ["--ok", "--warn"];
     var lineColor = data.line_color || "--accent";
+    var lineSuffix = data.line_suffix || "";
+    var barLabels = data.bar_labels || {};
     var svg = el("svg", {viewBox: "0 0 " + W + " " + H, role: "img"});
-    var iw = W - P.l - P.r, ih = H - P.t - P.b, n = points.length;
+    // Reserve extra right margin for the secondary (line) axis labels when a
+    // line is present, so they don't collide with the plot area.
+    var rpad = lineCat ? 34 : 0;
+    var iw = W - P.l - P.r - rpad, ih = H - P.t - P.b, n = points.length;
     var lmax = 1, rmax = 1;
     points.forEach(function(p){
       bars.forEach(function(b){ lmax = Math.max(lmax, (p.values && p.values[b]) || 0); });
@@ -385,7 +400,9 @@ def _fmt(value) -> str:
     var YR = function(v){ return P.t + ih * (1 - v / rmax); };
     var cx = function(i){ return P.l + slot * i + slot / 2; };
     hGrid(svg, YL, lmax, iw);
+    if(lineCat) rAxis(svg, YR, rmax, iw, lineSuffix, tok(lineColor));
     svg.appendChild(el("line", {class: "axis-base", x1: P.l, x2: P.l + iw, y1: P.t + ih, y2: P.t + ih}));
+    var cols = [];
     points.forEach(function(p, i){
       var gx = P.l + slot * i + (slot - group) / 2;
       bars.forEach(function(b, bi){
@@ -394,6 +411,11 @@ def _fmt(value) -> str:
         svg.appendChild(el("rect", {x: gx + bw * bi, y: P.t + ih - h, width: Math.max(bw - 2, 1),
           height: h, rx: "2", fill: tok(barColors[bi % barColors.length])}));
       });
+      // Per-column tooltip label: each bar series + the line value.
+      var parts = [p.key];
+      bars.forEach(function(b){ parts.push((barLabels[b] || b) + " " + fmt((p.values && p.values[b]) || 0)); });
+      if(lineCat){ parts.push((barLabels[lineCat] || lineCat) + " " + fmt((p.values && p.values[lineCat]) || 0) + lineSuffix); }
+      cols.push({x: cx(i), x0: P.l + slot * i, w: slot, key: p.key, label: parts.join("  \\u00b7  ")});
       if(i % Math.max(1, Math.ceil(n / 8)) === 0){
         var t = el("text", {x: cx(i), y: H - 8, "text-anchor": "middle", fill: tok("--muted"),
           "font-size": "10", "font-family": "var(--mono)"});
@@ -409,6 +431,7 @@ def _fmt(value) -> str:
         svg.appendChild(el("circle", {cx: cx(i), cy: YR((p.values && p.values[lineCat]) || 0), r: "2.5", fill: tok(lineColor)}));
       });
     }
+    attachTip(host, svg, cols);
     host.appendChild(svg);
   }
 

cometx/cli/admin_growth_report.py

@@ -11,11 +11,13 @@
 #  Copyright (c) 2024 Cometx Development
 #      Team. All rights reserved.
 # ****************************************
-"""cometx admin growth-report — cross-platform use-case growth & rates, per
-workspace/department (Opik + EM + MPM), rendered as a self-contained HTML page.
+"""cometx admin growth-report — org-wide people/usage growth from the admin
+chargeback report, rendered as a self-contained HTML page.
 
-Distinct from `admin usage-report` (experiment counts over time, PDF/Streamlit):
-growth-report tracks cross-platform use-case creation growth and rates.
+Sources exclusively from `/api/admin/chargeback/report` (admin API key
+required): organization overview, users, leaderboards, and a
+personal-vs-service-account split. Distinct from `admin usage-report`
+(experiment counts over time, PDF/Streamlit).
 """
 
 from __future__ import annotations
@@ -112,11 +114,17 @@ def _extract_service_account_names(payload) -> "set[str] | None":
     """Defensively unwrap the `/admin/service-accounts` response into a
     flat set of account names, tolerating several plausible response
     shapes since the exact schema isn't documented in this codebase: a
-    bare list of entries, or a dict wrapping that list under a common
-    container key (`serviceAccounts`, `accounts`, `users`). Each entry may
-    be a plain string, or a dict carrying the name under `name`,
-    `username`, or `email` (mirrors `_extract_licensed_users`'s defensive
-    style in `admin_growth_users.py`).
+    bare list of entries, or a dict wrapping that list under a
+    service-account-specific container key (`serviceAccounts`,
+    `accounts`). Each entry may be a plain string, or a dict carrying the
+    name under `name`, `username`, or `email` (mirrors
+    `_extract_licensed_users`'s defensive style in `admin_growth_users.py`).
+
+    A generic `users` key is deliberately NOT accepted: if the endpoint
+    ever returned the full user roster under it, every user would be
+    classified as a service account and the report would label that
+    inversion authoritative ("admin API"). Better to fail the parse and
+    fall back to the labeled heuristic.
 
     Returns `None` (not an empty set) when the payload cannot be honestly
     parsed as a service-account container -- either because its shape
@@ -131,7 +139,7 @@ def _extract_service_account_names(payload) -> "set[str] | None":
     container = payload
     recognized = isinstance(payload, list)
     if isinstance(payload, dict):
-        for key in ("serviceAccounts", "accounts", "users"):
+        for key in ("serviceAccounts", "accounts"):
             if key in payload:
                 container = payload[key]
                 recognized = isinstance(container, list)
@@ -493,8 +501,6 @@ def _build_unified_section(
                             "labels": {"total": "Total", "active": "Active"},
                             "colors": ["--sdk", "--ok"],
                             "points": ws_active_pts,
-                            "window_start": None,
-                            "window_end": None,
                         },
                     }
                 )
@@ -544,12 +550,15 @@ def _build_unified_section(
                             "points": churn_pts,
                             "bars": ["added", "deleted"],
                             "line": "rate",
-                            "bar_labels": {"added": "Added", "deleted": "Deleted"},
+                            "bar_labels": {
+                                "added": "Added",
+                                "deleted": "Deleted",
+                                "rate": "Growth rate",
+                            },
                             "bar_colors": ["--ok", "--warn"],
                             "line_label": "Growth rate",
                             "line_color": "--accent",
-                            "window_start": None,
-                            "window_end": None,
+                            "line_suffix": "%",
                         },
                     }
                 )
@@ -601,7 +610,7 @@ def _build_unified_section(
             {
                 "label": f"New in {self.window or '7d'} (% of base)",
                 "value": f"{wg['pct']}%",
-                "sub": f"+{wg['new_in']} new",
+                "sub": f"+{wg['new_in']} new (est. from earliest member)",
             },
             {
                 "label": "Active workspaces %",
@@ -686,8 +695,6 @@ def _build_people_section(self, users, now_ms, window=None):
                     "labels": {"total": "Total", "active": "Active"},
                     "colors": ["--sdk", "--ok"],
                     "points": active_pts,
-                    "window_start": None,
-                    "window_end": None,
                 },
             }
         ]
@@ -709,7 +716,10 @@ def _build_people_section(self, users, now_ms, window=None):
                     "id": "chart-people-adoption-rate",
                     "kind": "lines",
                     "title": "Adoption rates",
-                    "hint": f"active users / total; active window {self.active_window} · {self._units_adverb()}",
+                    "hint": (
+                        f"active users / total; active window "
+                        f"{self.active_window} · {self._units_adverb()}"
+                    ),
                     "legend": [
                         {"label": lbl, "color": col} for _, lbl, col in rate_spec
                     ],
@@ -718,8 +728,6 @@ def _build_people_section(self, users, now_ms, window=None):
                         "labels": {k: lbl for k, lbl, _ in rate_spec},
                         "colors": [col for _, _, col in rate_spec],
                         "points": rate_pts,
-                        "window_start": None,
-                        "window_end": None,
                     },
                 }
             )
@@ -731,7 +739,10 @@ def _build_people_section(self, users, now_ms, window=None):
                     "id": "chart-people-capability",
                     "kind": "lines",
                     "title": "Active users by capability",
-                    "hint": f"active window {self.active_window} · {self._units_adverb()}",
+                    "hint": (
+                        f"active window {self.active_window} · "
+                        f"{self._units_adverb()}"
+                    ),
                     "legend": [
                         {"label": "EM", "color": "--sdk"},
                         {"label": "Opik", "color": "--accent"},
@@ -741,8 +752,6 @@ def _build_people_section(self, users, now_ms, window=None):
                         "labels": {"em": "EM", "opik": "Opik"},
                         "colors": ["--sdk", "--accent"],
                         "points": cap_pts,
-                        "window_start": None,
-                        "window_end": None,
                     },
                 }
             )
@@ -771,8 +780,6 @@ def _build_people_section(self, users, now_ms, window=None):
                         },
                         "colors": ["--sdk", "--accent", "--warn"],
                         "points": em_pts,
-                        "window_start": None,
-                        "window_end": None,
                     },
                 }
             )
@@ -799,8 +806,6 @@ def _build_people_section(self, users, now_ms, window=None):
                         },
                         "colors": ["--accent", "--ok"],
                         "points": opik_pts,
-                        "window_start": None,
-                        "window_end": None,
                     },
                 }
             )
@@ -813,8 +818,8 @@ def _build_people_section(self, users, now_ms, window=None):
                     "kind": "lines",
                     "title": "Users added vs. deleted",
                     "hint": (
-                        f"per period · {self._units_adverb()}; deletions reflect soft-deletes "
-                        "still present in the snapshot"
+                        f"per period · {self._units_adverb()}; deletions reflect "
+                        "soft-deletes still present in the snapshot"
                     ),
                     "legend": [
                         {"label": "Added", "color": "--ok"},
@@ -825,8 +830,6 @@ def _build_people_section(self, users, now_ms, window=None):
                         "labels": {"added": "Added", "deleted": "Deleted"},
                         "colors": ["--ok", "--warn"],
                         "points": user_churn,
-                        "window_start": None,
-                        "window_end": None,
                     },
                 }
             )
@@ -839,7 +842,7 @@ def _build_people_section(self, users, now_ms, window=None):
                 [
                     u.username,
                     _num(u.experiment_count),
-                    _num(u.data_logged_mb),
+                    _num(round(u.data_logged_mb)),
                     _num(u.opik_span_count) if u.opik_span_count is not None else "-",
                 ]
                 for u in top
@@ -1066,7 +1069,10 @@ def _scope_label(scope, org_workspaces, org_users, scoped_count=None):
         the rendered sections."""
         if scope is not None:
             n = scoped_count if scoped_count is not None else len(scope)
-            return f"Scoped to {n} selected workspace(s)"
+            return (
+                f"Scoped to {n} selected workspace(s) "
+                "(per-user totals remain org-wide)"
+            )
         if org_workspaces is not None:
             return (
                 f"Org-wide: {org_workspaces} workspaces, {org_users} users "