@drakulavich/zapara 0.7.1 → 0.7.3

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.7.3] - 2026-09-26
+
+### Added
+- `--verbose` prints timings and counts to stderr after the output, with no
+  path in them: files scanned and read, megabytes, milliseconds per stage,
+  versions, platform and CPU count. It is meant for diagnosing a slow run on
+  someone else's machine.
+- `zapara card` says `drawing the card…` on a terminal's stderr while the
+  browser engine renders the picture, which takes a few seconds.
+
+## [0.7.2] - 2026-09-26
+
+### Changed
+- Transcripts are read sixteen at a time instead of one by one. On a machine
+  with 1.6 GB of transcripts in a 14-day window, reading took 0.9 s instead
+  of 5.4 s.
+- Transcript lines older than the window's three-hour look-back are skipped
+  before parsing, except assistant replies, whose request ids dedupe output
+  tokens. A long session's file holds its whole history, and on one machine
+  59% of what a 14-day window read was such history. Results are unchanged.
+  Together with parallel reads, `zapara card --json` there went from 5.6 s to
+  about 2 s.
+
 ## [0.7.1] - 2026-09-25
 
 ### Added

package/README.md

@@ -135,12 +135,13 @@ If your card told you something about your week, star [the repository](https://g
 | `--projects <dir>` | Read this directory instead of `~/.claude/projects`. |
 | `--out <path>` | Where `card` writes instead of `~/Downloads`; the extension picks the format. |
 | `--no-color` | Plain glyphs and peaks with no ANSI codes. `NO_COLOR` in the environment does the same. |
+| `--verbose` | After the output, prints to stderr where the time went: files scanned and read, megabytes, and milliseconds for scanning, reading, analysis and the card's render, plus the zapara and Bun versions, platform and CPU count. Numbers only, no path, so the lines are safe to paste into an issue when zapara is slow on your machine. |
 | `-h`, `--help` | Usage, exit 0. |
 | `-V`, `--version` | The version from `package.json`, exit 0. |
 
 Levels: calm 0–29, warming 30–59, heating 60–84, fried 85–100.
 
-The grid and the day print a text table when stdout is a terminal and JSON otherwise, so `zapara | cat` prints JSON; no flag forces text in a pipe yet. `card` and `status` write their file and print their lines whether piped or not. `card` asks to open the picture only when stdin and stdout are both a terminal, and never on Windows. `card --json` is the exception: it prints the card's data and writes no file. `--json` changes nothing for `status`, whose line is already JSON and whose file is written either way.
+The grid and the day print a text table when stdout is a terminal and JSON otherwise, so `zapara | cat` prints JSON; no flag forces text in a pipe yet. `card` and `status` write their file and print their lines whether piped or not. `card` asks to open the picture only when stdin and stdout are both a terminal, and never on Windows. While the browser engine draws a picture, a terminal's stderr shows `drawing the card…`, cleared before the result. `card --json` is the exception: it prints the card's data and writes no file. `--json` changes nothing for `status`, whose line is already JSON and whose file is written either way.
 
 A run that works exits 0, and so does a window with no data, which prints an empty grid. Exit 1 is a failure zapara can name, printed as one line to stderr that never contains a path: the projects directory missing or unreadable, `status` unable to write its file, `card` unable to write its picture or to find a browser engine, `card` without `--out` on a machine with no `~/Downloads` folder, and whatever else goes wrong below the command line. Exit 2 is a usage error, such as a bad date, an unknown flag or a value flag given twice; it prints one line and a hint to `--help`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakulavich/zapara",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Cognitive load index for people driving Claude Code, computed locally from transcripts",
   "license": "MIT",
   "author": "Anton Yakutovich",

package/src/analyze.ts

@@ -1,11 +1,12 @@
-import { compareStrings, derive } from "./derive.ts";
+import { compareStrings, derive, windowBounds } from "./derive.ts";
 import { parseTranscript } from "./parse.ts";
 import type { Day, Transcript, Window } from "./types.ts";
 
 // Sorted by path so file discovery order cannot change a result.
 export function analyze(transcripts: Transcript[], w: Window): Day[] {
+  const { cutoffMs } = windowBounds(w);
   const events = [...transcripts]
     .sort((a, b) => compareStrings(a.path, b.path))
-    .flatMap((t) => parseTranscript(t.text));
+    .flatMap((t) => parseTranscript(t.text, cutoffMs));
   return derive(events, w);
 }

package/src/index.ts

@@ -1,14 +1,14 @@
 #!/usr/bin/env bun
 // Argument parsing, the clock, stdout and exit codes live here; everything else is pure.
 import { readFileSync, statSync } from "node:fs";
-import { homedir } from "node:os";
+import { cpus, homedir } from "node:os";
 import { join } from "node:path";
 import { cardData, sentenceText } from "./card.ts";
 import { cardHtml } from "./cardhtml.ts";
 import { localDate } from "./derive.ts";
 import { loadAssets, openCard, renderCard } from "./image.ts";
 import { renderDay, renderJson, renderWeek } from "./render.ts";
-import { report } from "./report.ts";
+import { READERS, report, type Timing } from "./report.ts";
 import { renderStatus, statusOf } from "./status.ts";
 import { writeStatus } from "./statusfile.ts";
 import type { Day } from "./types.ts";
@@ -40,6 +40,7 @@ options:
   --json            the same data as JSON; a pipe gets JSON without asking
   --projects <dir>  read this directory instead of ~/.claude/projects
   --no-color        no ANSI colors; NO_COLOR does the same
+  --verbose         timings and counts on stderr, for a slow run
   -h, --help  -V, --version
 
 levels: calm 0-29  warming 30-59  heating 60-84  fried 85-100
@@ -47,7 +48,7 @@ levels: calm 0-29  warming 30-59  heating 60-84  fried 85-100
 bugs, ideas and a star: github.com/drakulavich/zapara`;
 const HINT = "run 'zapara --help' for usage";
 
-type Args = { command: "grid" | "day" | "card" | "status"; to: string; days: number; explain: boolean; json: boolean; out: string | null; projects: string; color: boolean };
+type Args = { command: "grid" | "day" | "card" | "status"; to: string; days: number; explain: boolean; json: boolean; out: string | null; projects: string; color: boolean; verbose: boolean };
 
 class UsageError extends Error {}
 // Thrown only at a flag position, never for a token consumed as another flag's
@@ -98,7 +99,7 @@ function windowOf(days: string | null, from: string | null, to: string | null, d
 }
 
 function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boolean): Args {
-  const a: Args = { command: "grid", to: localDate(now), days: 7, explain: false, json: false, out: null, projects: join(homedir(), ".claude", "projects"), color: isTTY && !env.NO_COLOR };
+  const a: Args = { command: "grid", to: localDate(now), days: 7, explain: false, json: false, out: null, projects: join(homedir(), ".claude", "projects"), color: isTTY && !env.NO_COLOR, verbose: false };
   let days: string | null = null;
   let from: string | null = null;
   let to: string | null = null;
@@ -134,6 +135,7 @@ function parseArgs(argv: string[], now: Date, env: NodeJS.ProcessEnv, isTTY: boo
       case "--json": bare(); jsonFlag = true; break;
       case "--explain": bare(); a.explain = true; break;
       case "--no-color": bare(); a.color = false; break;
+      case "--verbose": bare(); a.verbose = true; break;
       case "--projects": a.projects = value(); break;
       case "--from": from = value(); break;
       case "--to": to = value(); break;
@@ -173,9 +175,14 @@ async function main(): Promise<number> {
   const argv = process.argv.slice(2);
   const now = new Date();
   const a = parseArgs(argv, now, process.env, process.stdout.isTTY === true);
-  if (a.command === "card") return card(a);
-  if (a.command === "status") return status(a, now);
-  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now });
+  const timing = a.verbose ? ({} as Timing) : undefined;
+  const code = a.command === "card" ? await card(a, timing) : a.command === "status" ? await status(a, now, timing) : await table(a, now, timing);
+  if (timing) process.stderr.write(timingLines(timing));
+  return code;
+}
+
+async function table(a: Args, now: Date, timing?: Timing): Promise<number> {
+  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now }, timing);
   const data = a.command === "day" ? days[0] : days;
   if (a.json) console.log(renderJson(data!));
   else if (a.command === "day") console.log(renderDay(days[0]!, { explain: a.explain, color: a.color }));
@@ -184,8 +191,8 @@ async function main(): Promise<number> {
 }
 
 // The write comes first: a caller never reads a line that was not saved.
-async function status(a: Args, now: Date): Promise<number> {
-  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now });
+async function status(a: Args, now: Date, timing?: Timing): Promise<number> {
+  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days, now }, timing);
   const line = renderStatus(statusOf(days[0]!, now));
   await writeStatus(line, process.env);
   process.stdout.write(line);
@@ -202,8 +209,8 @@ function cardTarget(out: string | null): { path: string; label: string } {
   return { path: join(dir, "zapara-card.png"), label: "zapara-card.png to Downloads" };
 }
 
-async function card(a: Args): Promise<number> {
-  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days });
+async function card(a: Args, timing?: Timing): Promise<number> {
+  const days: Day[] = await report({ projects: a.projects, to: a.to, days: a.days }, timing);
   const data = cardData(days, { days: a.days });
   if (data === null) throw new Error(`no activity in the last ${a.days} days`);
   if (a.json) {
@@ -218,7 +225,16 @@ async function card(a: Args): Promise<number> {
     return 0;
   }
   const target = cardTarget(a.out);
-  await renderCard(cardHtml(data, await loadAssets()), target.path);
+  // The browser engine takes seconds; a person at a terminal is told why it waits.
+  const note = process.stderr.isTTY && !/\.html$/i.test(target.path);
+  if (note) process.stderr.write("drawing the card…");
+  const t = performance.now();
+  try {
+    await renderCard(cardHtml(data, await loadAssets()), target.path);
+  } finally {
+    if (note) process.stderr.write("\r\x1b[K");
+  }
+  if (timing) timing.render = { format: target.path.slice(target.path.lastIndexOf(".") + 1).toLowerCase(), ms: performance.now() - t };
   console.log(`${data.name}: ${sentenceText(data.sentence)}\nwrote ${target.label}`);
   if (process.stdin.isTTY && process.stdout.isTTY && process.platform !== "win32") {
     process.stdout.write("open it? [Y/n] ");
@@ -229,6 +245,20 @@ async function card(a: Args): Promise<number> {
   return 0;
 }
 
+// Numbers only: someone pastes these from another machine, and no path may leave it.
+function timingLines(t: Timing): string {
+  let ver = "?";
+  try { ver = version(); } catch {}
+  const row = (label: string, what: string, ms: number) => `${label.padEnd(8)}${what.padEnd(44)}${String(Math.round(ms)).padStart(7)} ms\n`;
+  const plural = (n: number, one: string) => `${n} ${one}${n === 1 ? "" : "s"}`;
+  return `zapara ${ver} · bun ${Bun.version} · ${process.platform} ${process.arch} · ${cpus().length} cpus\n`
+    + row("scan", `${plural(t.files, "file")}, ${t.inWindow} in window, ${plural(t.tailChecks, "tail check")}`, t.scanMs)
+    + row("read", `${plural(t.read, "file")}, ${(t.bytes / 1e6).toFixed(1)} MB, ${READERS} at a time`, t.readMs)
+    + row("analyze", "", t.analyzeMs)
+    + (t.render ? row("render", t.render.format, t.render.ms) : "")
+    + row("total", "", performance.now());
+}
+
 if (import.meta.main) {
   main().then((code) => process.exit(code), (e: unknown) => {
     if (e instanceof HelpRequested) { console.log(USAGE); process.exit(0); }

package/src/parse.ts

@@ -28,7 +28,26 @@ const firstText = (content: unknown): string | null => {
   return null;
 };
 
-export function parseTranscript(text: string): Event[] {
+// A record older than the look-back yields only events derive() drops, so it is
+// not parsed at all. Every "timestamp" in the line must be old, since a nested
+// one can differ from the record's own. The skip waits for a first timestamped
+// record, which the mode switches before it attach to; lines naming the two
+// tools whose result the human writes are always parsed, for their ids.
+// One pass over the line: it costs a fifth of JSON.parse.
+const SKIP_SCAN = new RegExp(`"timestamp":"([^"]{20,40})"|${QUESTION_TOOL}|${PLAN_TOOL}`, "g");
+function olderThan(line: string, cutoffMs: number): boolean {
+  // Parsing an assistant record can update seenRequestIds even when its events
+  // are outside the window. Preserve that deduplication state across the skip.
+  if (line.includes('"requestId"')) return false;
+  let any = false;
+  for (const m of line.matchAll(SKIP_SCAN)) {
+    if (m[1] === undefined || !(Date.parse(m[1]) < cutoffMs)) return false;
+    any = true;
+  }
+  return any;
+}
+
+export function parseTranscript(text: string, cutoffMs = -Infinity): Event[] {
   const events: Event[] = [];
   let lastTs: number | null = null;
   let lastMode: string | null = null;
@@ -42,6 +61,7 @@ export function parseTranscript(text: string): Event[] {
 
   for (const line of text.split("\n")) {
     if (line.trim() === "") continue;
+    if (lastTs !== null && lastTs < cutoffMs && olderThan(line, cutoffMs)) continue;
     let rec: unknown;
     try { rec = JSON.parse(line); } catch { continue; }
     if (!isObj(rec)) continue;

package/src/report.ts

@@ -1,17 +1,43 @@
 import { readFile } from "node:fs/promises";
 import { analyze } from "./analyze.ts";
 import { windowBounds } from "./derive.ts";
-import { scan } from "./scan.ts";
+import { scan, type ScanStats } from "./scan.ts";
 import type { Day, Transcript } from "./types.ts";
 
 export type ReportOptions = { projects: string; to: string; days: number; now?: Date };
+// What --verbose prints about a run: counts and milliseconds, never a path.
+export type Timing = ScanStats & { inWindow: number; read: number; bytes: number; scanMs: number; readMs: number; analyzeMs: number; render?: { format: string; ms: number } };
 
-export async function report(o: ReportOptions): Promise<Day[]> {
+// Reading one file at a time left the disk idle between files: 1.6 GB took 5.4 s
+// sequentially and 0.9 s in parallel. The cap keeps open files well under the limit.
+export const READERS = 16;
+
+export async function report(o: ReportOptions, timing?: Timing): Promise<Day[]> {
   const window = { to: o.to, days: o.days, now: o.now };
-  const paths = await scan(o.projects, windowBounds(window).cutoffMs);
+  const stats: ScanStats = { files: 0, tailChecks: 0 };
+  let t = performance.now();
+  const paths = await scan(o.projects, windowBounds(window).cutoffMs, stats);
+  const scanMs = performance.now() - t;
+  t = performance.now();
+  const texts: (string | null)[] = new Array(paths.length).fill(null);
+  let next = 0;
+  let bytes = 0;
+  const reader = async (): Promise<void> => {
+    while (next < paths.length) {
+      const i = next++;
+      try {
+        const buf = await readFile(paths[i]!);
+        bytes += buf.length;
+        texts[i] = buf.toString("utf8");
+      } catch { /* vanished or unreadable: skip */ }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(READERS, paths.length) }, reader));
+  const readMs = performance.now() - t;
   const transcripts: Transcript[] = [];
-  for (const path of paths) {
-    try { transcripts.push({ path, text: await readFile(path, "utf8") }); } catch { /* vanished or unreadable: skip */ }
-  }
-  return analyze(transcripts, window);
+  paths.forEach((path, i) => { if (texts[i] !== null) transcripts.push({ path, text: texts[i]! }); });
+  t = performance.now();
+  const days = analyze(transcripts, window);
+  if (timing) Object.assign(timing, { ...stats, inWindow: paths.length, read: transcripts.length, bytes, scanMs, readMs, analyzeMs: performance.now() - t });
+  return days;
 }

package/src/scan.ts

@@ -2,8 +2,12 @@ import type { Dirent } from "node:fs";
 import { open, readdir, stat } from "node:fs/promises";
 import { join } from "node:path";
 
+// What --verbose reports about the walk: transcripts seen, and how many of them
+// were opened only to read the tail of a file older than the window by mtime.
+export type ScanStats = { files: number; tailChecks: number };
+
 // A `subagents` directory holds the parent agent's conversation, not the human's.
-export async function scan(projects: string, cutoffMs: number): Promise<string[]> {
+export async function scan(projects: string, cutoffMs: number, stats: ScanStats = { files: 0, tailChecks: 0 }): Promise<string[]> {
   // No path in either message: the CLI never prints one.
   let root;
   try {
@@ -15,23 +19,28 @@ export async function scan(projects: string, cutoffMs: number): Promise<string[]
     throw new Error("projects directory not found (pass --projects <dir>)");
   }
   const out: string[] = [];
-  await collect(projects, root, cutoffMs, out);
+  await collect(projects, root, cutoffMs, out, stats);
   return out.sort();
 }
 
 // One unreadable directory costs only itself. Symlinks are not followed: Claude
 // Code never writes one, and following one is how a loop or $HOME would get in.
-async function collect(dir: string, entries: Dirent[], cutoffMs: number, out: string[]): Promise<void> {
+async function collect(dir: string, entries: Dirent[], cutoffMs: number, out: string[], stats: ScanStats): Promise<void> {
   for (const entry of entries) {
     const full = join(dir, entry.name);
     if (entry.isDirectory()) {
       if (entry.name === "subagents") continue;
       try {
-        await collect(full, await readdir(full, { withFileTypes: true }), cutoffMs, out);
+        await collect(full, await readdir(full, { withFileTypes: true }), cutoffMs, out, stats);
       } catch {}
     } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+      stats.files++;
       try {
-        if ((await stat(full)).mtimeMs >= cutoffMs || (await lastTimestampMs(full)) >= cutoffMs) out.push(full);
+        if ((await stat(full)).mtimeMs >= cutoffMs) out.push(full);
+        else {
+          stats.tailChecks++;
+          if ((await lastTimestampMs(full)) >= cutoffMs) out.push(full);
+        }
       } catch {}
     }
   }