@hank-warren/pi-stats 0.4.1 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @hank-warren/pi-stats
 
+## 0.4.2
+
+### Patch Changes
+
+- Label the month the heatmap grid ends in. The axis keyed each month change off its column's Monday and dropped a label that no longer fit at the right edge, so the current month was missing from the axis on 56% of days. Columns are now named for the month holding their Thursday, and the rightmost label is clamped left instead of dropped.
+
 ## 0.4.1
 
 ### Patch Changes

package/README.md

@@ -99,3 +99,7 @@ Sessions remain authoritative. For fast repeat opens, the extension stores one d
 The location follows `PI_CODING_AGENT_DIR`. The cache contains file stat identity, session IDs/timestamps/working directories, model names, tool names with call and error counts, usage counters, and de-duplication fingerprints. It never stores prompts, responses, tool arguments, tool output, or other conversation content. It is written atomically with mode `0600` and can be deleted at any time; the next `/stats` invocation rebuilds it.
 
 No network or billing API is used. Displayed costs are the estimates already recorded by Pi.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.

package/cache.ts

@@ -11,7 +11,7 @@ const SKIP_DIRECTORIES = new Set(["subagent-artifacts"]);
 /** Extensions record out-of-transcript model usage in <agentDir>/<extension>/usage.jsonl. */
 const USAGE_SIDECAR_NAMES = new Set(["usage.jsonl", "usage.jsonl.1"]);
 
-export interface ScanOptions {
+interface ScanOptions {
 	agentDir: string;
 	activeSessionDir?: string;
 	env?: NodeJS.ProcessEnv;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-stats",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "A compact /stats dashboard for all-time Pi token usage, including persisted subagents.",
   "type": "module",
   "keywords": [
@@ -23,7 +23,7 @@
   },
   "homepage": "https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-stats#readme",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.19.0"
   },
   "pi": {
     "extensions": [

package/stats.ts

@@ -43,7 +43,7 @@ function firstNumber(source: Record<string, unknown>, names: string[]): number {
 	return 0;
 }
 
-export function normalizeUsage(value: unknown): UsageTotals | undefined {
+function normalizeUsage(value: unknown): UsageTotals | undefined {
 	const usage = object(value);
 	if (!usage) return undefined;
 	const cost = object(usage.cost);
@@ -375,7 +375,7 @@ function hasPersistedSubagentChild(record: UsageRecord, sessionPaths: ReadonlySe
 	return record.toolName === "subagent" && Boolean(record.childSessionFiles?.some((file) => sessionPaths.has(resolve(file))));
 }
 
-export function deduplicateToolCalls(sessions: readonly SessionRecord[]): ToolCallRecord[] {
+function deduplicateToolCalls(sessions: readonly SessionRecord[]): ToolCallRecord[] {
 	const seen = new Set<string>();
 	const result: ToolCallRecord[] = [];
 	for (const session of sessions) {

package/types.ts

@@ -8,7 +8,7 @@ export interface UsageTotals {
 	calls: number;
 }
 
-export type SessionSource = "main" | "subagent";
+type SessionSource = "main" | "subagent";
 
 export interface UsageRecord {
 	fingerprint: string;

package/widget.ts

@@ -10,12 +10,12 @@ import {
 	type UsageTotals,
 } from "./types.ts";
 
-export type WidgetState =
+type WidgetState =
 	| { kind: "loading"; completed: number; total: number }
 	| { kind: "error"; message: string }
 	| { kind: "ready"; snapshot: StatsSnapshot };
 
-export interface StatsWidgetOptions {
+interface StatsWidgetOptions {
 	theme: Theme;
 	requestRender: () => void;
 	onClose: () => void;
@@ -37,7 +37,7 @@ const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "
 const RANGES: StatsRange[] = ["all", "7d", "30d"];
 const RANGE_LABELS: Record<StatsRange, string> = { all: "All time", "7d": "Last 7 days", "30d": "Last 30 days" };
 
-export type StatsTab = "overview" | "models" | "tools" | "projects";
+type StatsTab = "overview" | "models" | "tools" | "projects";
 const TABS: StatsTab[] = ["overview", "models", "tools", "projects"];
 const TAB_LABELS: Record<StatsTab, string> = { overview: "Overview", models: "Models", tools: "Tools", projects: "Projects" };
 
@@ -76,6 +76,45 @@ function localDay(time: number): string {
 	return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
 }
 
+/**
+ * The heatmap's month label row: one character per week column, `weeks` wide.
+ *
+ * A column belongs to the month holding its Thursday, so it is named for whichever month
+ * owns four or more of its seven days. Labels are placed right to left because only the
+ * right edge is constrained: each one sits at its month's first column unless its
+ * neighbour crowds it, and shifts left just enough to stay clear.
+ */
+export function monthAxis(start: Date, weeks: number): string {
+	const monthOf = (week: number): number => {
+		const thursday = new Date(start);
+		thursday.setDate(thursday.getDate() + week * 7 + 3);
+		return thursday.getMonth();
+	};
+	/** Three characters plus a space, so neighbouring labels never touch. */
+	const spacing = 4;
+
+	const boundaries: { column: number; month: number }[] = [];
+	for (let week = 0; week < weeks; week++) {
+		const month = monthOf(week);
+		if (month !== monthOf(week - 1)) boundaries.push({ column: week, month });
+	}
+	// A grid too short to leave its month has no boundary to label, so name it after its
+	// last column like every other grid.
+	if (boundaries.length === 0) boundaries.push({ column: 0, month: monthOf(weeks - 1) });
+
+	const placed: { column: number; month: number }[] = [];
+	let rightmost = weeks - 3;
+	for (let index = boundaries.length - 1; index >= 0 && rightmost >= 0; index--) {
+		const column = Math.min(boundaries[index]!.column, rightmost);
+		placed.unshift({ column, month: boundaries[index]!.month });
+		rightmost = column - spacing;
+	}
+
+	let row = "";
+	for (const { column, month } of placed) row = row.padEnd(column, " ") + MONTHS[month]!;
+	return row.padEnd(weeks, " ").slice(0, weeks);
+}
+
 function padRight(value: string, width: number): string {
 	const clipped = truncateToWidth(value, Math.max(0, width), "");
 	return clipped + " ".repeat(Math.max(0, width - visibleWidth(clipped)));
@@ -424,22 +463,7 @@ export class StatsWidget implements Component {
 		const gap = Math.max(1, width - visibleWidth(heading) - visibleWidth(legend) - 1);
 		const lines = [`${heading}${" ".repeat(gap)}${theme.fg("dim", legend)}`];
 
-		let months = " ".repeat(HEATMAP_LABEL_WIDTH);
-		let lastLabel = -4;
-		for (let week = 0; week < weeks; week++) {
-			const date = new Date(start);
-			date.setDate(date.getDate() + week * 7);
-			const previous = new Date(date);
-			previous.setDate(previous.getDate() - 7);
-			if ((week === 0 || date.getMonth() !== previous.getMonth()) && week - lastLabel >= 4 && week + 3 <= weeks) {
-				months += MONTHS[date.getMonth()]!;
-				lastLabel = week;
-				week += 2;
-			} else {
-				months += " ";
-			}
-		}
-		lines.push(theme.fg("dim", months));
+		lines.push(theme.fg("dim", " ".repeat(HEATMAP_LABEL_WIDTH) + monthAxis(start, weeks)));
 
 		for (let weekday = 0; weekday < 7; weekday++) {
 			const label = weekday === 0 ? "Mon" : weekday === 2 ? "Wed" : weekday === 4 ? "Fri" : "   ";