@hank-warren/pi-stats 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @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
+
+- c079c51: Scan sessions through a bounded worker pool instead of one file at a time.
+
+  The stats scan now runs an ordered pool capped at eight concurrent readers, reduced by the discovery index, which shortens a cold scan over a large session history. Results stay in discovery order regardless of completion order, and progress is reported monotonically.
+
+  Cancellation is settled rather than abandoned: an abort stops further work being assigned and publishes nothing afterwards, but waits for reads already in flight, so the caller's `catch` never runs while file reads are still landing in the result array or progress is still being reported into a dashboard that is being torn down.
+
 ## 0.4.0
 
 ### Minor 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;
@@ -240,6 +240,64 @@ export function statsCachePath(agentDir: string): string {
 	return join(agentDir, "pi-stats", "cache.json");
 }
 
+export async function mapConcurrentOrdered<T, R>(
+	items: readonly T[],
+	limit: number,
+	worker: (item: T, index: number) => Promise<R>,
+	onProgress?: (completed: number, total: number) => void,
+	signal?: AbortSignal,
+): Promise<R[]> {
+	if (!Number.isSafeInteger(limit) || limit <= 0) throw new Error("concurrency limit must be positive");
+	const results = new Array<R>(items.length);
+	let nextIndex = 0;
+	let completed = 0;
+	// The first failure (an abort, a worker throw, or a progress callback that
+	// throws) stops work being assigned and stops anything else being published,
+	// but never abandons work already in flight: the caller's `catch` must not
+	// run while file reads are still landing in `results` and progress is still
+	// being reported into a widget that is about to be torn down.
+	let failure: unknown;
+	const failed = () => failure !== undefined;
+	const run = async () => {
+		while (!failed()) {
+			try {
+				signal?.throwIfAborted();
+			} catch (error) {
+				failure ??= error;
+				return;
+			}
+			const index = nextIndex;
+			if (index >= items.length) return;
+			nextIndex += 1;
+			try {
+				const value = await worker(items[index]!, index);
+				// Re-check *after* the await: an abort during the read must not still
+				// publish a result or a progress tick into a dashboard that is being
+				// torn down. A sibling runner may not have noticed the abort yet.
+				signal?.throwIfAborted();
+				if (failed()) return;
+				results[index] = value;
+				completed += 1;
+				onProgress?.(completed, items.length);
+			} catch (error) {
+				failure ??= error;
+				return;
+			}
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => run()));
+	if (failed()) throw failure;
+	return results;
+}
+
+type ScannedFile = {
+	file: string;
+	record?: CachedFileRecord;
+	reused: boolean;
+	unreadable: boolean;
+	changed: boolean;
+};
+
 export async function scanStats(options: ScanOptions): Promise<StatsIndex> {
 	const roots = await resolveSessionRoots(options);
 	const sessionFiles = await discoverJsonlFiles(roots, options.signal);
@@ -260,45 +318,65 @@ export async function scanStats(options: ScanOptions): Promise<StatsIndex> {
 	};
 	let changed = options.force === true || !loaded.valid;
 
-	for (let index = 0; index < files.length; index++) {
-		options.signal?.throwIfAborted();
-		const file = files[index]!;
-		try {
-			const metadata = await stat(file);
-			const previous = loaded.cache.files[file];
-			if (!options.force && sameFile(previous, metadata.size, metadata.mtimeMs)) {
-				next.files[file] = previous!;
-				diagnostics.reusedFiles++;
-			} else if (sidecars.has(file)) {
-				const parsed = parseUsageSidecar(file, await readFile(file, "utf8"));
-				next.files[file] = {
-					size: metadata.size,
-					mtimeMs: metadata.mtimeMs,
-					sidecar: parsed.records,
-					malformedLines: parsed.malformedLines,
-				};
-				diagnostics.parsedFiles++;
-				changed = true;
-			} else {
+	const scanned = await mapConcurrentOrdered(
+		files,
+		8,
+		async (file): Promise<ScannedFile> => {
+			options.signal?.throwIfAborted();
+			try {
+				const metadata = await stat(file);
+				const previous = loaded.cache.files[file];
+				if (!options.force && sameFile(previous, metadata.size, metadata.mtimeMs)) {
+					return { file, record: previous!, reused: true, unreadable: false, changed: false };
+				}
+				if (sidecars.has(file)) {
+					const parsed = parseUsageSidecar(file, await readFile(file, "utf8"));
+					return {
+						file,
+						record: {
+							size: metadata.size,
+							mtimeMs: metadata.mtimeMs,
+							sidecar: parsed.records,
+							malformedLines: parsed.malformedLines,
+						},
+						reused: false,
+						unreadable: false,
+						changed: true,
+					};
+				}
 				const parsed = parseSessionText(file, await readFile(file, "utf8"));
-				next.files[file] = {
-					size: metadata.size,
-					mtimeMs: metadata.mtimeMs,
-					...(parsed.ignored ? { ignored: true as const } : {}),
-					...(parsed.session ? { session: parsed.session } : {}),
-					malformedLines: parsed.malformedLines,
+				return {
+					file,
+					record: {
+						size: metadata.size,
+						mtimeMs: metadata.mtimeMs,
+						...(parsed.ignored ? { ignored: true as const } : {}),
+						...(parsed.session ? { session: parsed.session } : {}),
+						malformedLines: parsed.malformedLines,
+					},
+					reused: false,
+					unreadable: false,
+					changed: true,
 				};
-				diagnostics.parsedFiles++;
-				changed = true;
+			} catch {
+				options.signal?.throwIfAborted();
+				return { file, reused: false, unreadable: true, changed: true };
 			}
-			const current = next.files[file]!;
-			if (current.ignored) diagnostics.ignoredFiles++;
-			diagnostics.malformedLines += current.malformedLines;
-		} catch {
-			diagnostics.unreadableFiles++;
-			changed = true;
+		},
+		options.onProgress,
+		options.signal,
+	);
+
+	for (const result of scanned) {
+		if (result.record) {
+			next.files[result.file] = result.record;
+			if (result.reused) diagnostics.reusedFiles++;
+			else diagnostics.parsedFiles++;
+			if (result.record.ignored) diagnostics.ignoredFiles++;
+			diagnostics.malformedLines += result.record.malformedLines;
 		}
-		options.onProgress?.(index + 1, files.length);
+		if (result.unreadable) diagnostics.unreadableFiles++;
+		if (result.changed) changed = true;
 	}
 
 	if (Object.keys(loaded.cache.files).some((file) => !(file in next.files))) changed = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-stats",
-  "version": "0.4.0",
+  "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" : "   ";