claude-attribution 1.0.0

package/src/commands/pr.ts

@@ -0,0 +1,164 @@
+/**
+ * claude-attribution pr — create a PR with AI metrics embedded automatically.
+ *
+ * Usage: claude-attribution pr [title] [--draft] [--base <branch>]
+ *
+ * If title is omitted, it is derived from the current branch name.
+ * Reads .github/PULL_REQUEST_TEMPLATE.md if present; otherwise uses a
+ * built-in minimal template. Metrics are injected at the
+ * <!-- claude-attribution metrics --> placeholder, or appended if missing.
+ *
+ * Requires `gh` (GitHub CLI) to be installed and authenticated.
+ */
+import { readFile, writeFile, unlink, mkdtemp } from "fs/promises";
+import { existsSync } from "fs";
+import { resolve, join } from "path";
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { tmpdir } from "os";
+import { collectMetrics, renderMetrics } from "../metrics/collect.ts";
+
+const execFileAsync = promisify(execFile);
+
+const METRICS_PLACEHOLDER = "<!-- claude-attribution metrics -->";
+
+const BUILTIN_TEMPLATE = `## Description
+
+<!-- What does this PR do? -->
+
+## Testing
+
+<!-- How has this been tested? -->
+
+## Checklist
+
+- [ ] Code follows project coding standards
+- [ ] Tests pass
+
+${METRICS_PLACEHOLDER}
+`;
+
+/**
+ * Derive a PR title from the current branch name.
+ * "COMM-1234/add-user-auth" → "add user auth"
+ * "feature/my-great-feature" → "my great feature"
+ * "fix-null-pointer" → "fix null pointer"
+ */
+function titleFromBranch(branch: string): string {
+	// Strip leading ticket prefix (e.g. COMM-1234/, JIRA-99/)
+	const withoutTicket = branch.replace(/^[A-Z]+-\d+\//, "");
+	// Strip common prefixes like feature/, fix/, chore/
+	const withoutPrefix = withoutTicket.replace(
+		/^(feature|fix|chore|feat|refactor|docs|test)\//,
+		"",
+	);
+	// Replace hyphens and underscores with spaces
+	return withoutPrefix.replace(/[-_]/g, " ").trim();
+}
+
+async function getCurrentBranch(repoRoot: string): Promise<string> {
+	const { stdout } = await execFileAsync(
+		"git",
+		["rev-parse", "--abbrev-ref", "HEAD"],
+		{ cwd: repoRoot },
+	);
+	return stdout.trim();
+}
+
+async function checkGhInstalled(): Promise<boolean> {
+	try {
+		await execFileAsync("gh", ["--version"]);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+async function main() {
+	const repoRoot = resolve(process.cwd());
+
+	// Parse args: [title] [--draft] [--base <branch>]
+	const args = process.argv.slice(2);
+	let title: string | undefined;
+	let draft = false;
+	let base: string | undefined;
+
+	for (let i = 0; i < args.length; i++) {
+		if (args[i] === "--draft") {
+			draft = true;
+		} else if (args[i] === "--base" && i + 1 < args.length) {
+			base = args[++i];
+		} else if (!args[i].startsWith("--")) {
+			title = args[i];
+		}
+	}
+
+	// Derive title from branch name if not provided
+	if (!title) {
+		const branch = await getCurrentBranch(repoRoot);
+		title = titleFromBranch(branch);
+		if (!title) {
+			console.error("Error: Could not derive PR title from branch name.");
+			console.error(
+				'Usage: claude-attribution pr "feat: my title" [--draft] [--base <branch>]',
+			);
+			process.exit(1);
+		}
+		console.log(`Using title derived from branch: "${title}"`);
+	}
+
+	// Check gh is available
+	if (!(await checkGhInstalled())) {
+		console.error("Error: GitHub CLI (gh) is not installed or not on PATH.");
+		console.error("Install it from: https://cli.github.com");
+		process.exit(1);
+	}
+
+	// Collect metrics
+	console.log("Collecting metrics...");
+	const metricsData = await collectMetrics(undefined, repoRoot);
+	const metricsBlock = renderMetrics(metricsData);
+
+	// Load PR template
+	const templatePath = join(repoRoot, ".github", "PULL_REQUEST_TEMPLATE.md");
+	let template = existsSync(templatePath)
+		? await readFile(templatePath, "utf8")
+		: BUILTIN_TEMPLATE;
+
+	// Inject metrics at placeholder or append
+	let body: string;
+	if (template.includes(METRICS_PLACEHOLDER)) {
+		body = template.replace(METRICS_PLACEHOLDER, metricsBlock);
+	} else {
+		body = template.trimEnd() + "\n\n" + metricsBlock;
+	}
+
+	// Write body to a temp file (avoids shell quoting issues)
+	const tmpDir = await mkdtemp(join(tmpdir(), "claude-attribution-pr-"));
+	const bodyFile = join(tmpDir, "pr-body.md");
+	try {
+		await writeFile(bodyFile, body);
+
+		// Build gh pr create args
+		const ghArgs = ["pr", "create", "--title", title, "--body-file", bodyFile];
+		if (draft) ghArgs.push("--draft");
+		if (base) ghArgs.push("--base", base);
+
+		console.log("Creating PR...");
+		const { stdout } = await execFileAsync("gh", ghArgs, { cwd: repoRoot });
+		const prUrl = stdout.trim();
+		console.log(`\n✓ PR created: ${prUrl}`);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		console.error(`Error creating PR: ${msg}`);
+		process.exit(1);
+	} finally {
+		await unlink(bodyFile).catch(() => {});
+		await execFileAsync("rmdir", [tmpDir]).catch(() => {});
+	}
+}
+
+main().catch((err) => {
+	console.error("Error:", err);
+	process.exit(1);
+});

package/src/export/pr-summary.ts

@@ -0,0 +1,204 @@
+/**
+ * PR-level attribution aggregator + Datadog push.
+ *
+ * Run from GitHub Actions on PR merge. Reads attribution git notes for the
+ * PR's commits, aggregates to a PR-level payload, and pushes metrics + an
+ * event to Datadog using the v2 REST API.
+ *
+ * Required env (supplied by GHA workflow):
+ *   PR_NUMBER            — PR number (e.g. "42")
+ *   GITHUB_REPOSITORY    — "owner/repo"
+ *   PR_AUTHOR            — GitHub login of PR author
+ *   DATADOG_API_KEY      — Datadog API key (org-level GHA secret)
+ *
+ * Optional env:
+ *   DATADOG_SITE         — Datadog intake site (default: "datadoghq.com")
+ *   GITHUB_BASE_REF      — base branch name for tagging (default: "main")
+ *
+ * If DATADOG_API_KEY is unset the script runs in dry-run mode: it prints
+ * the payload as JSON to stdout and exits 0. This lets you test the script
+ * locally without a key.
+ */
+import { resolve } from "path";
+import {
+	listNotes,
+	readNote,
+	getBranchCommitShas,
+} from "../attribution/git-notes.ts";
+import {
+	aggregateTotals,
+	type AttributionResult,
+	type FileAttribution,
+} from "../attribution/differ.ts";
+
+interface MetricPoint {
+	timestamp: number;
+	value: number;
+}
+
+interface MetricSeries {
+	metric: string;
+	/** 3 = gauge */
+	type: 3;
+	points: MetricPoint[];
+	tags: string[];
+}
+
+interface DatadogEventPayload {
+	title: string;
+	text: string;
+	tags: string[];
+	alert_type: "info";
+}
+
+async function pushMetrics(
+	series: MetricSeries[],
+	apiKey: string,
+	site: string,
+): Promise<void> {
+	const res = await fetch(`https://api.${site}/api/v2/series`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json", "DD-API-KEY": apiKey },
+		body: JSON.stringify({ series }),
+	});
+	if (!res.ok) {
+		throw new Error(`Datadog metrics API ${res.status}: ${await res.text()}`);
+	}
+}
+
+async function pushEvent(
+	payload: DatadogEventPayload,
+	apiKey: string,
+	site: string,
+): Promise<void> {
+	const res = await fetch(`https://api.${site}/api/v1/events`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json", "DD-API-KEY": apiKey },
+		body: JSON.stringify(payload),
+	});
+	if (!res.ok) {
+		throw new Error(`Datadog events API ${res.status}: ${await res.text()}`);
+	}
+}
+
+async function main() {
+	const repoRoot = resolve(process.cwd());
+
+	const prNumber = process.env.PR_NUMBER ?? "";
+	const repo = process.env.GITHUB_REPOSITORY ?? "";
+	const author = process.env.PR_AUTHOR ?? "";
+	const baseRef = process.env.GITHUB_BASE_REF ?? "main";
+	const apiKey = process.env.DATADOG_API_KEY ?? "";
+	const site = process.env.DATADOG_SITE ?? "datadoghq.com";
+	const dryRun = !apiKey;
+
+	// Gather commits on this branch that have attribution notes
+	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;
+
+	// Read notes with concurrency limit to avoid process storms on large PRs
+	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);
+		notes.push(
+			...(await Promise.all(batch.map((sha) => readNote(repoRoot, sha)))),
+		);
+	}
+	const results = notes.filter((n): n is AttributionResult => n !== null);
+
+	if (results.length === 0) {
+		console.log(
+			"[pr-summary] No attribution notes found for this PR — skipping Datadog push.",
+		);
+		process.exit(0);
+	}
+
+	// Last-wins per file: sort ascending so later commits overwrite earlier ones.
+	// Prevents line-count inflation when the same file appears in multiple commits.
+	const sorted = [...results].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);
+		}
+	}
+	const { ai, human, total, pctAi } = aggregateTotals([
+		...lastSeenByFile.values(),
+	]);
+
+	// Use branch from the most recent note; fall back to env var
+	const branch = results[results.length - 1]?.branch ?? baseRef;
+
+	const tags = [
+		`repo:${repo}`,
+		`pr:${prNumber}`,
+		`branch:${branch}`,
+		`author:${author}`,
+		`tool:claude-code`,
+	];
+	const timestamp = Math.floor(Date.now() / 1000);
+
+	const series: MetricSeries[] = [
+		{
+			metric: "claude_attribution.ai_lines",
+			type: 3,
+			points: [{ timestamp, value: ai }],
+			tags,
+		},
+		{
+			metric: "claude_attribution.human_lines",
+			type: 3,
+			points: [{ timestamp, value: human }],
+			tags,
+		},
+		{
+			metric: "claude_attribution.total_lines",
+			type: 3,
+			points: [{ timestamp, value: total }],
+			tags,
+		},
+		{
+			metric: "claude_attribution.pct_ai",
+			type: 3,
+			points: [{ timestamp, value: pctAi }],
+			tags,
+		},
+	];
+
+	const event: DatadogEventPayload = {
+		title: `PR #${prNumber} merged — ${pctAi}% AI (claude-code)`,
+		text: `repo: ${repo}\nbranch: ${branch}\nai: ${ai} / human: ${human} / total: ${total}`,
+		tags,
+		alert_type: "info",
+	};
+
+	if (dryRun) {
+		console.log("[pr-summary] DRY RUN — DATADOG_API_KEY not set. Would push:");
+		console.log(JSON.stringify({ series, event }, null, 2));
+		process.exit(0);
+	}
+
+	await Promise.all([
+		pushMetrics(series, apiKey, site),
+		pushEvent(event, apiKey, site),
+	]);
+
+	console.log(
+		`[pr-summary] Pushed to Datadog: PR #${prNumber} — ${pctAi}% AI, ${ai}/${total} lines`,
+	);
+}
+
+main().catch((err) => {
+	console.error("[pr-summary] Error:", err);
+	process.exit(1);
+});

package/src/hooks/post-tool-use.ts

@@ -0,0 +1,105 @@
+/**
+ * PostToolUse hook — snapshot file AFTER Claude edits + log all tool calls.
+ *
+ * Registered in .claude/settings.json for matcher: ".*"
+ * (Runs for every tool, but only saves checkpoints for write tools.)
+ *
+ * Claude Code passes a JSON payload via stdin:
+ * {
+ *   session_id: string,
+ *   tool_name: string,
+ *   tool_input: { file_path?: string, ... },
+ *   tool_response: unknown
+ * }
+ */
+import { resolve, join } from "path";
+import { mkdir, appendFile } from "fs/promises";
+import { saveCheckpoint, SESSION_ID_RE } from "../attribution/checkpoint.ts";
+import { readStdin, WRITE_TOOLS, getFilePath } from "../lib/hooks.ts";
+import {
+	otelEndpoint,
+	otelHeaders,
+	readOtelContext,
+	buildToolCallSpan,
+	exportOtlpSpans,
+} from "../attribution/otel.ts";
+
+interface HookPayload {
+	session_id: string;
+	tool_name: string;
+	tool_input: Record<string, unknown>;
+	tool_response?: unknown;
+}
+
+async function main() {
+	const raw = await readStdin();
+	if (!raw.trim()) process.exit(0);
+
+	let payload: HookPayload;
+	try {
+		payload = JSON.parse(raw) as HookPayload;
+	} catch {
+		process.exit(0);
+	}
+
+	const { session_id, tool_name, tool_input } = payload;
+	const repoRoot = resolve(process.cwd());
+
+	// Log every tool call
+	const logEntry = {
+		timestamp: new Date().toISOString(),
+		session: session_id,
+		tool: tool_name,
+	};
+
+	try {
+		const logDir = join(repoRoot, ".claude", "logs");
+		await mkdir(join(logDir, "sessions"), { recursive: true });
+		const line = JSON.stringify(logEntry) + "\n";
+		await appendFile(join(logDir, "tool-usage.jsonl"), line);
+		// Guard against path traversal via a crafted session_id
+		if (SESSION_ID_RE.test(session_id)) {
+			await appendFile(join(logDir, "sessions", `${session_id}.jsonl`), line);
+		}
+	} catch {
+		// Non-fatal
+	}
+
+	// Save after-checkpoint for write tools
+	if (!WRITE_TOOLS.has(tool_name)) process.exit(0);
+
+	const filePath = getFilePath(tool_input);
+	if (!filePath) process.exit(0);
+
+	const absPath = resolve(filePath);
+
+	try {
+		await saveCheckpoint(session_id, absPath, "after");
+	} catch (err) {
+		console.error("[claude-attribution] post-tool-use error:", err);
+	}
+
+	// OTel: emit child span for this tool call
+	const endpoint = otelEndpoint();
+	if (endpoint) {
+		try {
+			const repoRoot = resolve(process.cwd());
+			const ctx = await readOtelContext(repoRoot);
+			if (ctx?.lastToolCallStart) {
+				const span = buildToolCallSpan(
+					ctx,
+					tool_name,
+					getFilePath(tool_input) ?? null,
+					new Date().toISOString(),
+				);
+				await exportOtlpSpans([span], endpoint, otelHeaders());
+			}
+		} catch {
+			// Silent — never block Claude
+		}
+	}
+
+	process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/src/hooks/pre-tool-use.ts

@@ -0,0 +1,95 @@
+/**
+ * PreToolUse hook — snapshot file content BEFORE Claude edits it.
+ *
+ * Registered in .claude/settings.json for tools: Edit, Write, MultiEdit
+ *
+ * Claude Code passes a JSON payload via stdin:
+ * {
+ *   session_id: string,
+ *   tool_name: string,
+ *   tool_input: { file_path?: string, path?: string, ... }
+ * }
+ */
+import { resolve } from "path";
+import {
+	loadCheckpoint,
+	saveCheckpoint,
+	writeCurrentSession,
+} from "../attribution/checkpoint.ts";
+import { readStdin, WRITE_TOOLS, getFilePath } from "../lib/hooks.ts";
+import {
+	otelEndpoint,
+	otelHeaders,
+	readOtelContext,
+	writeOtelContext,
+	makeTraceId,
+	makeSpanId,
+} from "../attribution/otel.ts";
+
+interface HookPayload {
+	session_id: string;
+	tool_name: string;
+	tool_input: Record<string, unknown>;
+}
+
+async function main() {
+	const raw = await readStdin();
+	if (!raw.trim()) process.exit(0);
+
+	let payload: HookPayload;
+	try {
+		payload = JSON.parse(raw) as HookPayload;
+	} catch {
+		process.exit(0);
+	}
+
+	const { session_id, tool_name, tool_input } = payload;
+	if (!WRITE_TOOLS.has(tool_name)) process.exit(0);
+
+	const filePath = getFilePath(tool_input);
+	if (!filePath) process.exit(0);
+
+	const absPath = resolve(filePath);
+	const repoRoot = resolve(process.cwd());
+
+	try {
+		// Only save before-checkpoint if one doesn't already exist for this session+file.
+		// This preserves the original human-authored state when Claude edits a file
+		// multiple times in one session — we want "before Claude touched it at all",
+		// not "before Claude's second edit".
+		const existing = await loadCheckpoint(session_id, absPath, "before");
+		if (!existing) {
+			await saveCheckpoint(session_id, absPath, "before");
+		}
+		await writeCurrentSession(repoRoot, session_id);
+	} catch (err) {
+		// Never block Claude — soft fail
+		console.error("[claude-attribution] pre-tool-use error:", err);
+	}
+
+	// OTel: record tool call start time in context file
+	if (otelEndpoint()) {
+		try {
+			const now = new Date().toISOString();
+			let ctx = await readOtelContext(repoRoot);
+			if (!ctx) {
+				ctx = {
+					traceId: makeTraceId(),
+					rootSpanId: makeSpanId(),
+					sessionId: session_id,
+					startTime: now,
+					lastToolCallStart: now,
+				};
+			} else {
+				ctx.lastToolCallStart = now;
+			}
+			await writeOtelContext(repoRoot, ctx);
+		} catch {
+			// Silent — never block Claude
+		}
+	}
+
+	process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/src/hooks/stop.ts

@@ -0,0 +1,33 @@
+/**
+ * Stop hook (SessionEnd) — runs when a Claude Code session ends.
+ *
+ * Intentionally does NOT clean up checkpoints. The .after snapshots in
+ * /tmp/claude-attribution/<session_id>/ need to survive session close because
+ * a developer may close Claude Code before committing. If checkpoints were
+ * deleted here, commits made after reopening Claude Code would show 0% AI.
+ *
+ * /tmp is cleaned by the OS on reboot. Stale checkpoints are harmless.
+ */
+
+import { readStdin } from "../lib/hooks.ts";
+
+interface HookPayload {
+	session_id: string;
+	stop_hook_active?: boolean;
+}
+
+async function main() {
+	const raw = await readStdin();
+	if (!raw.trim()) process.exit(0);
+
+	// Parse to validate payload shape — no action needed
+	try {
+		JSON.parse(raw) as HookPayload;
+	} catch {
+		// ignore
+	}
+
+	process.exit(0);
+}
+
+main().catch(() => process.exit(0));

package/src/hooks/subagent.ts

@@ -0,0 +1,72 @@
+/**
+ * SubagentStart / SubagentStop hook — log subagent activity.
+ *
+ * Registered in .claude/settings.json for both SubagentStart and SubagentStop events.
+ * Runs whenever Claude Code launches a subagent (Agent tool call) or when one completes.
+ *
+ * Logs each event to:
+ *   .claude/logs/agent-activity.jsonl       (all sessions, append-only)
+ *   .claude/logs/sessions/<session_id>.jsonl (per-session, append-only)
+ *
+ * The /metrics command reads agent-activity.jsonl to count agent invocations by type.
+ * `promptPreview` is truncated to 200 characters to limit log file size.
+ */
+import { resolve, join } from "path";
+import { mkdir, appendFile } from "fs/promises";
+import { SESSION_ID_RE } from "../attribution/checkpoint.ts";
+import { readStdin } from "../lib/hooks.ts";
+
+interface HookPayload {
+	hook_event_name: string;
+	session_id: string;
+	agent_id?: string;
+	subagent_type?: string;
+	subagent_prompt?: string;
+}
+
+async function main() {
+	const raw = await readStdin();
+	if (!raw.trim()) process.exit(0);
+
+	let payload: HookPayload;
+	try {
+		payload = JSON.parse(raw) as HookPayload;
+	} catch {
+		process.exit(0);
+	}
+
+	const {
+		hook_event_name,
+		session_id,
+		agent_id,
+		subagent_type,
+		subagent_prompt,
+	} = payload;
+
+	const entry = {
+		timestamp: new Date().toISOString(),
+		event: hook_event_name,
+		session: session_id,
+		agentId: agent_id ?? null,
+		subagentType: subagent_type ?? null,
+		promptPreview: subagent_prompt ? subagent_prompt.slice(0, 200) : null,
+	};
+
+	try {
+		const repoRoot = resolve(process.cwd());
+		const logDir = join(repoRoot, ".claude", "logs");
+		await mkdir(join(logDir, "sessions"), { recursive: true });
+		const line = JSON.stringify(entry) + "\n";
+		await appendFile(join(logDir, "agent-activity.jsonl"), line);
+		// Guard against path traversal via a crafted session_id
+		if (SESSION_ID_RE.test(session_id)) {
+			await appendFile(join(logDir, "sessions", `${session_id}.jsonl`), line);
+		}
+	} catch {
+		// Non-fatal
+	}
+
+	process.exit(0);
+}
+
+main().catch(() => process.exit(0));