claude-attribution 1.0.0

package/src/lib/hooks.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared utilities for Claude Code hook scripts.
+ *
+ * Claude Code invokes each hook script as a subprocess and sends the event
+ * payload via stdin as a single JSON object. These helpers handle stdin
+ * reading and tool-input field extraction consistently across all hook
+ * scripts (pre-tool-use, post-tool-use, subagent, stop).
+ *
+ * Compatible with bun, tsx, and node — no Bun-specific APIs are used.
+ */
+
+/**
+ * Read all of stdin to a string.
+ *
+ * Uses the async iterator protocol over `process.stdin`, which works correctly
+ * across bun, tsx (Node.js), and plain node without runtime-specific APIs like
+ * `Bun.stdin.stream()`.
+ */
+export async function readStdin(): Promise<string> {
+	const chunks: Buffer[] = [];
+	for await (const chunk of process.stdin as AsyncIterable<Buffer>) {
+		chunks.push(chunk);
+	}
+	return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * The set of Claude Code tools that write file content.
+ *
+ * These are the tools that trigger checkpoint snapshots in pre-tool-use and
+ * post-tool-use hooks. Matches the PreToolUse hook matcher pattern:
+ * "Edit|Write|MultiEdit|NotebookEdit"
+ */
+export const WRITE_TOOLS = new Set([
+	"Edit",
+	"Write",
+	"MultiEdit",
+	"NotebookEdit",
+]);
+
+/**
+ * Extract the target file path from a Claude Code tool input payload.
+ *
+ * Different tools use different field names for the file path argument:
+ *   - Edit, Write, MultiEdit → `file_path`
+ *   - NotebookEdit           → `notebook_path`
+ *   - Bash                   → `path` (not a write tool, included for completeness)
+ *
+ * Returns `undefined` if no path field is found (e.g., for tools that don't
+ * operate on files, like WebSearch or AskUserQuestion).
+ */
+export function getFilePath(
+	toolInput: Record<string, unknown>,
+): string | undefined {
+	return (
+		(toolInput["file_path"] as string | undefined) ??
+		(toolInput["path"] as string | undefined) ??
+		(toolInput["notebook_path"] as string | undefined)
+	);
+}

package/src/metrics/calculate.ts

@@ -0,0 +1,21 @@
+/**
+ * Claude Code metrics calculator.
+ *
+ * Usage: claude-attribution metrics [session-id]
+ *
+ * Reads tool logs, agent activity, transcripts, and git attribution notes,
+ * then outputs compact markdown suitable for pasting into a PR description.
+ *
+ * See src/metrics/collect.ts for data collection and rendering logic.
+ */
+import { collectMetrics, renderMetrics } from "./collect.ts";
+
+async function main() {
+	const data = await collectMetrics(process.argv[2]);
+	console.log(renderMetrics(data));
+}
+
+main().catch((err) => {
+	console.error("Error:", err);
+	process.exit(1);
+});

package/src/metrics/collect.ts

@@ -0,0 +1,369 @@
+/**
+ * Shared metrics collection and rendering for calculate.ts and pr.ts.
+ *
+ * Exports:
+ *   collectMetrics(sessionIdArg?, repoRoot?) — gathers all data sources
+ *   renderMetrics(data) — compact markdown for PR descriptions
+ */
+import { readFile } from "fs/promises";
+import { existsSync } from "fs";
+import { resolve, join, relative } from "path";
+import { parseTranscript, type TranscriptResult } from "./transcript.ts";
+import {
+	listNotes,
+	readNote,
+	getBranchCommitShas,
+} from "../attribution/git-notes.ts";
+import {
+	aggregateTotals,
+	type AttributionResult,
+	type FileAttribution,
+} from "../attribution/differ.ts";
+import { SESSION_ID_RE } from "../attribution/checkpoint.ts";
+
+export interface MetricsData {
+	repoRoot: string;
+	sessionId: string;
+	toolCounts: Map<string, number>;
+	agentCounts: Map<string, number>;
+	transcript: TranscriptResult | null;
+	attributions: AttributionResult[];
+	lastSeenByFile: Map<string, FileAttribution>;
+	allTranscripts: TranscriptResult[];
+}
+
+async function readSessionStart(repoRoot: string): Promise<Date | null> {
+	const markerPath = join(
+		repoRoot,
+		".claude",
+		"attribution-state",
+		"session-start",
+	);
+	if (!existsSync(markerPath)) return null;
+	try {
+		const raw = await readFile(markerPath, "utf8");
+		const marker = JSON.parse(raw) as { timestamp?: string };
+		return marker.timestamp ? new Date(marker.timestamp) : null;
+	} catch {
+		return null;
+	}
+}
+
+async function readJsonlForSession(
+	filePath: string,
+	sessionId: string,
+	since?: Date,
+): Promise<unknown[]> {
+	if (!existsSync(filePath)) return [];
+	const raw = await readFile(filePath, "utf8");
+	const results: unknown[] = [];
+	for (const line of raw.split("\n")) {
+		if (!line.trim()) continue;
+		try {
+			const entry = JSON.parse(line) as {
+				session?: string;
+				timestamp?: string;
+			};
+			if (entry.session !== sessionId) continue;
+			if (since && entry.timestamp && new Date(entry.timestamp) < since)
+				continue;
+			results.push(entry);
+		} catch {
+			// Skip malformed lines
+		}
+	}
+	return results;
+}
+
+async function resolveSessionId(repoRoot: string): Promise<string | null> {
+	const toolLog = join(repoRoot, ".claude", "logs", "tool-usage.jsonl");
+	if (!existsSync(toolLog)) return null;
+	const raw = await readFile(toolLog, "utf8");
+	const lines = raw.trim().split("\n").filter(Boolean);
+	const last = lines.at(-1);
+	if (!last) return null;
+	try {
+		return (JSON.parse(last) as { session?: string }).session ?? null;
+	} catch {
+		return null;
+	}
+}
+
+async function getBranchAttribution(
+	repoRoot: string,
+	sessionStart: Date | null,
+): Promise<AttributionResult[]> {
+	const [allShas, branchShas] = await Promise.all([
+		listNotes(repoRoot),
+		getBranchCommitShas(repoRoot),
+	]);
+	const branchSet = new Set(branchShas);
+	const shasToRead =
+		branchShas.length > 0
+			? allShas.filter((sha) => branchSet.has(sha))
+			: allShas;
+
+	const CONCURRENCY = 8;
+	const notes: Awaited<ReturnType<typeof readNote>>[] = [];
+	for (let i = 0; i < shasToRead.length; i += CONCURRENCY) {
+		const batch = shasToRead.slice(i, i + CONCURRENCY);
+		const batchResults = await Promise.all(
+			batch.map((sha) => readNote(repoRoot, sha)),
+		);
+		notes.push(...batchResults);
+	}
+	const results = notes.filter((n): n is AttributionResult => n !== null);
+	if (sessionStart) {
+		return results.filter((r) => new Date(r.timestamp) >= sessionStart);
+	}
+	return results;
+}
+
+export function kFormat(n: number): string {
+	return n >= 1000 ? `${Math.floor(n / 1000)}K` : String(n);
+}
+
+export async function collectMetrics(
+	sessionIdArg?: string,
+	repoRoot?: string,
+): Promise<MetricsData> {
+	const root = repoRoot ?? resolve(process.cwd());
+	const logDir = join(root, ".claude", "logs");
+
+	const sessionId = sessionIdArg ?? (await resolveSessionId(root));
+	if (!sessionId) {
+		console.error(
+			"Error: No session ID found. Logs may be empty or not yet generated.",
+		);
+		console.error("Usage: claude-attribution metrics [session-id]");
+		process.exit(1);
+	}
+
+	const sessionStart = await readSessionStart(root);
+
+	const [toolEntries, agentEntries, transcript, attributions] =
+		await Promise.all([
+			readJsonlForSession(
+				join(logDir, "tool-usage.jsonl"),
+				sessionId,
+				sessionStart ?? undefined,
+			) as Promise<{ tool?: string }[]>,
+			readJsonlForSession(
+				join(logDir, "agent-activity.jsonl"),
+				sessionId,
+				sessionStart ?? undefined,
+			) as Promise<{ subagentType?: string; event?: string }[]>,
+			parseTranscript(sessionId, root),
+			getBranchAttribution(root, sessionStart),
+		]);
+
+	// Tool counts
+	const toolCounts = new Map<string, number>();
+	for (const e of toolEntries) {
+		if (e.tool) toolCounts.set(e.tool, (toolCounts.get(e.tool) ?? 0) + 1);
+	}
+
+	// Agent counts (SubagentStart events only)
+	const agentCounts = new Map<string, number>();
+	for (const e of agentEntries.filter((e) => e.event === "SubagentStart")) {
+		const t = e.subagentType ?? "unknown";
+		agentCounts.set(t, (agentCounts.get(t) ?? 0) + 1);
+	}
+
+	// Last-wins per file for attribution
+	const sorted = [...attributions].sort(
+		(a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime(),
+	);
+	const lastSeenByFile = new Map<string, FileAttribution>();
+	for (const result of sorted) {
+		for (const file of result.files) {
+			lastSeenByFile.set(file.path, file);
+		}
+	}
+
+	// Multi-session rollup: collect all unique session IDs from branch commits
+	const branchSessionIds = new Set(
+		attributions
+			.map((r) => r.session)
+			.filter((s): s is string => s !== null && SESSION_ID_RE.test(s)),
+	);
+	if (SESSION_ID_RE.test(sessionId)) branchSessionIds.add(sessionId);
+	branchSessionIds.delete(sessionId);
+
+	let allTranscripts: TranscriptResult[] = transcript ? [transcript] : [];
+	if (branchSessionIds.size > 0) {
+		const otherIds = [...branchSessionIds].filter((id) =>
+			SESSION_ID_RE.test(id),
+		);
+		const otherTranscripts = (
+			await Promise.all(otherIds.map((id) => parseTranscript(id, root)))
+		).filter((t): t is TranscriptResult => t !== null);
+		allTranscripts = [...allTranscripts, ...otherTranscripts];
+	}
+
+	return {
+		repoRoot: root,
+		sessionId,
+		toolCounts,
+		agentCounts,
+		transcript,
+		attributions,
+		lastSeenByFile,
+		allTranscripts,
+	};
+}
+
+export function renderMetrics(data: MetricsData): string {
+	const {
+		repoRoot,
+		toolCounts,
+		agentCounts,
+		transcript,
+		lastSeenByFile,
+		allTranscripts,
+	} = data;
+
+	const lines: string[] = [];
+	const out = (s = "") => lines.push(s);
+
+	out("## Claude Code Metrics");
+	out();
+
+	// Headline: AI% + active time (most important stat, shown first)
+	const allFileStats = [...lastSeenByFile.values()];
+	const hasAttribution = allFileStats.length > 0;
+	if (hasAttribution) {
+		const { ai, total, pctAi } = aggregateTotals(allFileStats);
+		const activePart =
+			transcript && transcript.activeMinutes > 0
+				? ` · Active: ${transcript.activeMinutes}m`
+				: "";
+		out(
+			`**AI contribution: ~${pctAi}%** (${ai} of ${total} committed lines)${activePart}`,
+		);
+		out();
+	} else if (transcript && transcript.activeMinutes > 0) {
+		out(`**Active session time:** ${transcript.activeMinutes}m`);
+		out();
+	}
+
+	// Model usage table
+	if (transcript) {
+		out("| Model | Calls | Input | Output | Cache |");
+		out("|-------|-------|-------|--------|-------|");
+		for (const m of transcript.byModel) {
+			const cache = m.cacheCreationTokens + m.cacheReadTokens;
+			out(
+				`| ${m.modelShort} | ${m.calls} | ${kFormat(m.inputTokens)} | ${kFormat(m.outputTokens)} | ${kFormat(cache)} |`,
+			);
+		}
+		const { totals: t } = transcript;
+		const totalCache = t.totalCacheCreationTokens + t.totalCacheReadTokens;
+		out(
+			`| **Total** | ${t.totalCalls} | ${kFormat(t.totalInputTokens)} | ${kFormat(t.totalOutputTokens)} | ${kFormat(totalCache)} |`,
+		);
+		out();
+		out(`**Human prompts (steering effort):** ${transcript.humanPromptCount}`);
+		out();
+	}
+
+	// Multi-session rollup (shown when multiple Claude sessions contributed)
+	if (allTranscripts.length > 1) {
+		out(`### All Sessions on This Branch (${allTranscripts.length} sessions)`);
+		out();
+		const agg = allTranscripts.reduce(
+			(acc, t) => ({
+				totalCalls: acc.totalCalls + t.totals.totalCalls,
+				totalInputTokens: acc.totalInputTokens + t.totals.totalInputTokens,
+				totalOutputTokens: acc.totalOutputTokens + t.totals.totalOutputTokens,
+				totalCacheTokens:
+					acc.totalCacheTokens +
+					t.totals.totalCacheCreationTokens +
+					t.totals.totalCacheReadTokens,
+				humanPromptCount: acc.humanPromptCount + t.humanPromptCount,
+				activeMinutes: acc.activeMinutes + t.activeMinutes,
+			}),
+			{
+				totalCalls: 0,
+				totalInputTokens: 0,
+				totalOutputTokens: 0,
+				totalCacheTokens: 0,
+				humanPromptCount: 0,
+				activeMinutes: 0,
+			},
+		);
+		out("| API Calls | Input Tokens | Output Tokens | Cache Tokens |");
+		out("|-----------|--------------|---------------|--------------|");
+		out(
+			`| ${agg.totalCalls} | ${kFormat(agg.totalInputTokens)} | ${kFormat(agg.totalOutputTokens)} | ${kFormat(agg.totalCacheTokens)} |`,
+		);
+		out();
+		out(`**Total human prompts:** ${agg.humanPromptCount}`);
+		if (agg.activeMinutes > 0) {
+			out(`**Total active session time:** ${agg.activeMinutes}m`);
+		}
+		out();
+	}
+
+	// <details> block — tools, agents, per-file breakdown
+	const claudeFiles = [...lastSeenByFile.entries()].filter(
+		([, stats]) => stats.ai > 0 || stats.mixed > 0,
+	);
+	const hasTools = toolCounts.size > 0;
+	const hasAgents = agentCounts.size > 0;
+	const hasFiles = claudeFiles.length > 0;
+
+	const summaryParts: string[] = [];
+	if (hasTools) summaryParts.push("Tools");
+	if (hasAgents) summaryParts.push("Agents");
+	if (hasFiles) summaryParts.push("Files");
+	if (summaryParts.length === 0) summaryParts.push("Details");
+
+	out("<details>");
+	out(`<summary>${summaryParts.join(" · ")}</summary>`);
+	out();
+
+	if (hasTools) {
+		const toolLine = [...toolCounts.entries()]
+			.sort((a, b) => b[1] - a[1])
+			.map(([tool, count]) => `${tool} ×${count}`)
+			.join(", ");
+		out(`**Tools:** ${toolLine}`);
+		out();
+	} else {
+		out("_No tool usage logs found_");
+		out();
+	}
+
+	if (hasAgents) {
+		const agentLine = [...agentCounts.entries()]
+			.sort((a, b) => b[1] - a[1])
+			.map(([agent, count]) => `${agent} ×${count}`)
+			.join(", ");
+		out(`**Agents:** ${agentLine}`);
+		out();
+	}
+
+	if (hasFiles) {
+		out("#### Files");
+		out();
+		for (const [path, stats] of claudeFiles.sort()) {
+			const filePct =
+				stats.total > 0 ? Math.round((stats.ai / stats.total) * 100) : 0;
+			const relPath = relative(repoRoot, join(repoRoot, path));
+			out(`- \`${relPath}\` — ${filePct}% AI (${stats.ai} lines)`);
+		}
+		out();
+	} else if (!hasAttribution) {
+		out("_No attribution data found._");
+		out(
+			"_Attribution is recorded per-commit by the post-commit hook — ensure claude-attribution is installed._",
+		);
+		out();
+	}
+
+	out("</details>");
+	out();
+
+	return lines.join("\n");
+}

package/src/metrics/mark-start.ts

@@ -0,0 +1,40 @@
+/**
+ * Mark the start of a new work session for a Jira ticket or feature branch.
+ *
+ * Usage: <attribution-root>/src/run.sh <attribution-root>/src/metrics/mark-start.ts
+ * Or via the /start slash command installed by install.ts.
+ *
+ * Writes a JSON marker to .claude/attribution-state/session-start:
+ *   { "timestamp": "<ISO8601>", "sessionId": "<string | null>" }
+ *
+ * The /metrics command uses this marker to filter tool usage, token counts,
+ * and attribution notes to only activity after this timestamp. This prevents
+ * metrics from being inflated by work done on previous Jira tickets in the
+ * same long-running Claude Code session.
+ *
+ * Run this when you check out a new feature branch or start a new ticket.
+ */
+import { writeFile, mkdir } from "fs/promises";
+import { resolve, join } from "path";
+
+async function main() {
+	const repoRoot = resolve(process.cwd());
+	const stateDir = join(repoRoot, ".claude", "attribution-state");
+	await mkdir(stateDir, { recursive: true });
+
+	const marker = {
+		timestamp: new Date().toISOString(),
+		sessionId: process.env["CLAUDE_SESSION_ID"] ?? null,
+	};
+
+	await writeFile(join(stateDir, "session-start"), JSON.stringify(marker));
+	console.log(`Session start marked at ${marker.timestamp}`);
+	console.log(
+		"Run /metrics after your PR is ready to generate scoped metrics.",
+	);
+}
+
+main().catch((err) => {
+	console.error("Error:", err);
+	process.exit(1);
+});