claude-attribution 1.6.0 → 1.8.0

package/README.md

@@ -135,7 +135,7 @@ The installer makes the following changes to the target repo:
 
 **`.git/hooks/post-commit`** — runs attribution after every commit. If the repo already has a `post-commit` hook from Husky or another tool, the call is appended rather than replacing it. For Lefthook repos, the installer prints the config snippet to add manually.
 
-**`remote.origin.push` refspecs** — the installer adds two refspecs so that `git push` (without an explicit refspec) automatically includes both notes refs: `refs/notes/claude-attribution` (per-commit attribution) and `refs/notes/claude-attribution-map` (cumulative minimap). No pre-push hook is installed — a hook that pushes notes concurrently with the main push causes SSH connection conflicts on GitHub.
+**Best-effort notes sync** — after each commit, the post-commit hook writes the attribution notes locally and then tries to push `refs/notes/claude-attribution` and `refs/notes/claude-attribution-map` to `origin`. The commit note now carries durable session metadata too (model usage, notable tool counts, agent counts, skills, and session timing), so PR metrics can be rebuilt in CI even when local `.claude` logs and transcripts are unavailable. If a notes push is rejected because the remote ref moved first, it fetches the remote notes ref, runs `git notes merge`, and retries the push. No `pre-push` hook or `remote.origin.push` refspec is installed, so plain `git push` does not fail just because notes metadata raced elsewhere.
 
 **`.github/workflows/claude-attribution-pr.yml`** — GitHub Actions workflow that fires on every PR open and push. Injects metrics into the PR body automatically for PRs created outside Claude (Copilot, manual `gh pr create`, GitHub UI). Skips injection if the local `post-bash` hook already injected metrics on `opened`; always updates on `synchronize` (new commits).
 
@@ -182,7 +182,21 @@ git push origin refs/notes/claude-attribution-map
 
 ### Re-installing
 
-If you reinstall `claude-attribution` globally (e.g. after upgrading), re-run the installer — it updates the absolute paths in `settings.json` and the git hook:
+If you reinstall `claude-attribution` globally (e.g. after upgrading), you can now refresh every tracked repo in one shot:
+
+```bash
+claude-attribution update
+```
+
+The installer records each repo in a per-user registry at `~/.claude/claude-attribution/installed-repos.json`. `update` re-runs the installer for every still-valid tracked repo, skips repos already on the current CLI version, and prunes paths that no longer exist or are no longer git repos.
+
+To force a reinstall even when the recorded version already matches, use:
+
+```bash
+claude-attribution update --force
+```
+
+You can still re-run the installer manually for a single repo when needed:
 
 ```bash
 claude-attribution install ~/Code/your-repo
@@ -196,7 +210,7 @@ To remove claude-attribution from a repo:
 claude-attribution uninstall ~/Code/your-repo
 ```
 
-This removes hooks from `.claude/settings.json`, removes `.git/hooks/post-commit`, removes the slash commands, removes `.github/workflows/claude-attribution-pr.yml`, `.github/workflows/claude-attribution-export.yml`, and `.github/workflows/claude-attribution-gha.yml` (if present), and removes any legacy `pre-push` hooks (for example `.husky/pre-push` or `.git/hooks/pre-push`) if present. Attribution state (`.claude/attribution-state/`) and logs (`.claude/logs/`) are left in place. The `remote.origin.push` refspec is also removed from git config.
+This removes hooks from `.claude/settings.json`, removes `.git/hooks/post-commit`, removes the slash commands, removes `.github/workflows/claude-attribution-pr.yml`, `.github/workflows/claude-attribution-export.yml`, and `.github/workflows/claude-attribution-gha.yml` (if present), and removes any legacy `pre-push` hooks (for example `.husky/pre-push` or `.git/hooks/pre-push`) if present. Attribution state (`.claude/attribution-state/`) and logs (`.claude/logs/`) are left in place. Any legacy `remote.origin.push` notes refspecs are also removed from git config. The repo is also removed from the global installed-repo registry used by `claude-attribution update`.
 
 ---
 
@@ -353,7 +367,19 @@ Example output:
   "files": [
     { "path": "src/components/Foo.tsx", "ai": 82, "human": 10, "mixed": 2, "total": 94, "pctAi": 87 }
   ],
-  "totals": { "ai": 142, "human": 38, "mixed": 4, "total": 184, "pctAi": 77 }
+  "totals": { "ai": 142, "human": 38, "mixed": 4, "total": 184, "pctAi": 77 },
+  "modelUsage": [
+    { "modelFull": "claude-sonnet-4.5", "modelShort": "Sonnet", "calls": 12, "inputTokens": 54000, "outputTokens": 9000, "cacheCreationTokens": 3200, "cacheReadTokens": 18000 }
+  ],
+  "sessionMetrics": {
+    "toolCounts": { "WebSearch": 2, "WebFetch": 1 },
+    "agentCounts": { "code-review": 1 },
+    "skillNames": ["pr"],
+    "humanPromptCount": 6,
+    "activeMinutes": 28,
+    "aiMinutes": 18,
+    "humanMinutes": 10
+  }
 }
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-attribution",
-	"version": "1.6.0",
+	"version": "1.8.0",
 	"description": "AI code attribution tracking for Claude Code sessions — checkpoint-based line diff approach",
 	"type": "module",
 	"bin": {

package/src/__tests__/bulk-update.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { readInstalledRepoRegistry } from "../setup/installed-repos.ts";
+import {
+	CLI_BIN,
+	REPO_ROOT,
+	commitAll,
+	createTempContext,
+	initGitRepo,
+	runCommand,
+} from "./integration-helpers.ts";
+
+describe("bulk update command", () => {
+	test("updates tracked repos and prunes missing paths", async () => {
+		const ctx = await createTempContext("claude-attribution-bulk-update");
+		try {
+			const repoA = join(ctx.root, "repo-a");
+			const repoB = join(ctx.root, "repo-b");
+			await mkdir(repoA, { recursive: true });
+			await mkdir(repoB, { recursive: true });
+			await initGitRepo(repoA);
+			await initGitRepo(repoB);
+			await writeFile(join(repoA, "README.md"), "repo a\n");
+			await writeFile(join(repoB, "README.md"), "repo b\n");
+			await commitAll(repoA, "initial");
+			await commitAll(repoB, "initial");
+
+			await runCommand(CLI_BIN, ["install", repoA], {
+				cwd: repoA,
+				env: { HOME: ctx.home },
+			});
+			await runCommand(CLI_BIN, ["install", repoB], {
+				cwd: repoB,
+				env: { HOME: ctx.home },
+			});
+
+			await writeFile(
+				join(repoA, ".claude", "attribution-state", "installed-version"),
+				"0.9.0",
+			);
+			await writeFile(
+				join(repoB, ".claude", "attribution-state", "installed-version"),
+				"0.9.0",
+			);
+
+			const registryPath = join(
+				ctx.home,
+				".claude",
+				"claude-attribution",
+				"installed-repos.json",
+			);
+			const registry = JSON.parse(await readFile(registryPath, "utf8")) as Array<{
+				path: string;
+				firstInstalledAt: string;
+				lastUpdatedAt: string;
+				installedVersion?: string;
+			}>;
+			registry.push({
+				path: join(ctx.root, "missing-repo"),
+				firstInstalledAt: new Date(0).toISOString(),
+				lastUpdatedAt: new Date(0).toISOString(),
+				installedVersion: "0.1.0",
+			});
+			await writeFile(registryPath, JSON.stringify(registry, null, 2) + "\n");
+
+			const update = await runCommand(CLI_BIN, ["update"], {
+				cwd: ctx.repo,
+				env: { HOME: ctx.home },
+			});
+
+			expect(update.stdout).toContain("Pruned missing repo");
+			expect(update.stdout).toContain("Updated:");
+			expect(update.stdout).toContain("Summary: 2 updated, 0 already current, 1 pruned, 0 failed");
+
+			const packageVersion = JSON.parse(
+				await readFile(join(REPO_ROOT, "package.json"), "utf8"),
+			) as { version: string };
+			expect(
+				(await readFile(
+					join(repoA, ".claude", "attribution-state", "installed-version"),
+					"utf8",
+				)).trim(),
+			).toBe(packageVersion.version);
+			expect(
+				(await readFile(
+					join(repoB, ".claude", "attribution-state", "installed-version"),
+					"utf8",
+				)).trim(),
+			).toBe(packageVersion.version);
+
+			const tracked = await readInstalledRepoRegistry(ctx.home);
+			expect(tracked.map((record) => record.path).sort()).toEqual(
+				[repoA, repoB].sort(),
+			);
+		} finally {
+			await ctx.cleanup();
+		}
+	});
+});

package/src/__tests__/checkpoint.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir, writeFile } from "fs/promises";
+import { join } from "path";
+import {
+clearCheckpoints,
+loadCheckpoint,
+readCurrentSession,
+saveCheckpoint,
+validateSessionId,
+writeCurrentSession,
+} from "../attribution/checkpoint.ts";
+import { createTempContext } from "./integration-helpers.ts";
+
+describe("checkpoint", () => {
+test("saves, loads, and clears checkpoints", async () => {
+const ctx = await createTempContext("claude-attribution-checkpoint");
+try {
+const sessionId = "session-123";
+const filePath = join(ctx.repo, "src", "file.ts");
+await mkdir(join(ctx.repo, "src"), { recursive: true });
+await writeFile(filePath, "before\nafter");
+
+await saveCheckpoint(sessionId, filePath, "before");
+const before = await loadCheckpoint(sessionId, filePath, "before");
+expect(before?.filePath).toBe(filePath);
+expect(before?.lines).toEqual(["before", "after"]);
+expect(before?.timestamp).toMatch(/T/);
+
+await writeFile(filePath, "revised");
+await saveCheckpoint(sessionId, filePath, "after");
+const after = await loadCheckpoint(sessionId, filePath, "after");
+expect(after?.lines).toEqual(["revised"]);
+
+await clearCheckpoints(sessionId);
+expect(await loadCheckpoint(sessionId, filePath, "before")).toBeNull();
+expect(await loadCheckpoint(sessionId, filePath, "after")).toBeNull();
+} finally {
+await ctx.cleanup();
+}
+});
+
+test("handles missing files and current session markers", async () => {
+const ctx = await createTempContext("claude-attribution-session-marker");
+try {
+const sessionId = "session-abc";
+const missingFile = join(ctx.repo, "missing.ts");
+
+expect(await readCurrentSession(ctx.repo)).toBeNull();
+await writeCurrentSession(ctx.repo, sessionId);
+expect(await readCurrentSession(ctx.repo)).toBe(sessionId);
+
+await saveCheckpoint(sessionId, missingFile, "before");
+const checkpoint = await loadCheckpoint(sessionId, missingFile, "before");
+expect(checkpoint?.lines).toEqual([""]);
+
+await clearCheckpoints("missing-session");
+} finally {
+await ctx.cleanup();
+}
+});
+
+test("rejects invalid session identifiers", () => {
+expect(() => validateSessionId("ok_session-1")).not.toThrow();
+expect(() => validateSessionId("../escape")).toThrow(/Invalid session_id/);
+});
+});

package/src/__tests__/git-notes.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "bun:test";
+import { writeFile } from "fs/promises";
+import { join } from "path";
+import {
+buildAllAiResult,
+committedContent,
+committedContentAt,
+currentBranch,
+filesInCommit,
+filesInCommitAt,
+getBranchCommitShas,
+getCommitMeta,
+headSha,
+isKnownAiActorCommit,
+listNotes,
+readNote,
+writeNote,
+} from "../attribution/git-notes.ts";
+import {
+commitAll,
+createTempContext,
+currentSha,
+initGitRepo,
+runCommand,
+} from "./integration-helpers.ts";
+
+describe("git-notes", () => {
+test("reads repo metadata and writes attribution notes", async () => {
+const ctx = await createTempContext("claude-attribution-git-notes");
+try {
+await initGitRepo(ctx.repo);
+await writeFile(join(ctx.repo, "baseline.txt"), "baseline");
+await commitAll(ctx.repo, "baseline");
+const initialSha = await currentSha(ctx.repo);
+
+await writeFile(join(ctx.repo, "ai.txt"), "alpha\n\nbeta");
+await writeFile(
+join(ctx.repo, "binary.bin"),
+Buffer.from([0, 1, 2, 3]),
+);
+await commitAll(ctx.repo, "add AI-attributed files");
+const sha = await currentSha(ctx.repo);
+
+expect(await headSha(ctx.repo)).toBe(sha);
+expect(await currentBranch(ctx.repo)).not.toBeNull();
+
+const changedFiles = await filesInCommit(ctx.repo);
+expect(changedFiles.includes("ai.txt")).toBe(true);
+expect(changedFiles.includes("binary.bin")).toBe(true);
+
+const changedFilesAtSha = await filesInCommitAt(ctx.repo, sha);
+expect(changedFilesAtSha.includes("ai.txt")).toBe(true);
+expect(changedFilesAtSha.includes("binary.bin")).toBe(true);
+
+expect(await committedContent(ctx.repo, "ai.txt")).toBe("alpha\n\nbeta");
+expect(await committedContent(ctx.repo, "missing.txt")).toBeNull();
+expect(await committedContentAt(ctx.repo, sha, "ai.txt")).toBe(
+"alpha\n\nbeta",
+);
+expect(await committedContentAt(ctx.repo, sha, "missing.txt")).toBeNull();
+
+expect(await readNote(ctx.repo, sha)).toBeNull();
+expect(await listNotes(ctx.repo)).toEqual([]);
+
+const result = await buildAllAiResult(ctx.repo, sha);
+expect(result.commit).toBe(sha);
+expect(result.files).toHaveLength(1);
+expect(result.files[0]).toMatchObject({
+path: "ai.txt",
+ai: 2,
+human: 1,
+total: 3,
+pctAi: 67,
+});
+expect(result.totals).toMatchObject({ ai: 2, human: 1, total: 3, pctAi: 67 });
+
+const meta = await getCommitMeta(ctx.repo, sha);
+expect(meta.authorName).toBe("Test User");
+expect(meta.authorEmail).toBe("test@example.com");
+expect(meta.message).toBe("add AI-attributed files");
+expect(meta.timestamp).toMatch(/T/);
+
+await writeNote(result, ctx.repo, sha);
+const stored = await readNote(ctx.repo, sha);
+expect(stored?.totals).toEqual(result.totals);
+expect(await listNotes(ctx.repo)).toEqual([sha]);
+
+const branchShas = await getBranchCommitShas(ctx.repo);
+expect(branchShas.includes(sha)).toBe(true);
+expect(branchShas.includes(initialSha)).toBe(true);
+} finally {
+await ctx.cleanup();
+}
+});
+
+test("returns null for detached HEAD branches", async () => {
+const ctx = await createTempContext("claude-attribution-detached-head");
+try {
+await initGitRepo(ctx.repo);
+await writeFile(join(ctx.repo, "file.txt"), "content");
+await commitAll(ctx.repo, "initial");
+const sha = await currentSha(ctx.repo);
+
+await runCommand("git", ["checkout", sha], { cwd: ctx.repo });
+expect(await currentBranch(ctx.repo)).toBeNull();
+} finally {
+await ctx.cleanup();
+}
+});
+
+test("detects known AI actor commit metadata", () => {
+expect(
+isKnownAiActorCommit({
+authorName: "github-actions[bot]",
+authorEmail: "41898282+github-actions[bot]@users.noreply.github.com",
+message: "Automated commit",
+timestamp: new Date().toISOString(),
+}),
+).toBe(true);
+
+expect(
+isKnownAiActorCommit({
+authorName: "Test User",
+authorEmail: "test@example.com",
+message:
+"feat: add change\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>",
+timestamp: new Date().toISOString(),
+}),
+).toBe(true);
+
+expect(
+isKnownAiActorCommit({
+authorName: "Test User",
+authorEmail: "test@example.com",
+message: "Regular human commit",
+timestamp: new Date().toISOString(),
+}),
+).toBe(false);
+});
+});

package/src/__tests__/installed-repos.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { mkdir } from "fs/promises";
+import {
+	installedRepoRegistryPath,
+	pruneMissingInstalledRepos,
+	readInstalledRepoRegistry,
+	registerInstalledRepo,
+	unregisterInstalledRepo,
+	writeInstalledRepoRegistry,
+} from "../setup/installed-repos.ts";
+import { createTempContext, initGitRepo } from "./integration-helpers.ts";
+
+describe("installed repo registry", () => {
+	test("registers, updates, prunes, and unregisters repos", async () => {
+		const ctx = await createTempContext("claude-attribution-installed-repos");
+		try {
+			const repo1 = ctx.repo;
+			const repo2 = `${ctx.root}/second-repo`;
+			await mkdir(repo2, { recursive: true });
+			await initGitRepo(repo1);
+			await initGitRepo(repo2);
+
+			await registerInstalledRepo(repo1, "1.6.0", ctx.home);
+			await registerInstalledRepo(repo2, "1.6.0", ctx.home);
+			await registerInstalledRepo(repo1, "1.7.0", ctx.home);
+
+			const registryPath = installedRepoRegistryPath(ctx.home);
+			expect(registryPath).toContain(".claude/claude-attribution/installed-repos.json");
+
+			const records = await readInstalledRepoRegistry(ctx.home);
+			expect(records).toHaveLength(2);
+			expect(records.map((record) => record.path)).toEqual([repo1, repo2].sort());
+			expect(records.find((record) => record.path === repo1)?.installedVersion).toBe(
+				"1.7.0",
+			);
+
+			await unregisterInstalledRepo(repo2, ctx.home);
+			expect(await readInstalledRepoRegistry(ctx.home)).toHaveLength(1);
+
+			await writeInstalledRepoRegistry(
+				[
+					{
+						path: repo1,
+						firstInstalledAt: new Date(0).toISOString(),
+						lastUpdatedAt: new Date().toISOString(),
+						installedVersion: "1.7.0",
+					},
+					{
+						path: `${ctx.root}/missing-repo`,
+						firstInstalledAt: new Date(0).toISOString(),
+						lastUpdatedAt: new Date().toISOString(),
+						installedVersion: "1.0.0",
+					},
+				],
+				ctx.home,
+			);
+			const pruned = await pruneMissingInstalledRepos(ctx.home);
+			expect(pruned.kept).toHaveLength(1);
+			expect(pruned.removed).toHaveLength(1);
+			expect((await readInstalledRepoRegistry(ctx.home)).map((record) => record.path)).toEqual(
+				[repo1],
+			);
+		} finally {
+			await ctx.cleanup();
+		}
+	});
+});

package/src/__tests__/integration-helpers.ts

@@ -0,0 +1,132 @@
+import { execFile } from "child_process";
+import {
+	mkdir,
+	mkdtemp,
+	realpath,
+	readFile,
+	rm,
+	writeFile,
+} from "fs/promises";
+import { tmpdir } from "os";
+import { dirname, join, resolve } from "path";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+
+export const REPO_ROOT = resolve(import.meta.dir, "..", "..");
+export const CLI_BIN = join(REPO_ROOT, "bin", "claude-attribution");
+
+export interface CommandResult {
+	stdout: string;
+	stderr: string;
+	exitCode: number;
+}
+
+export interface TempTestContext {
+	root: string;
+	home: string;
+	repo: string;
+	cleanup: () => Promise<void>;
+}
+
+export async function runCommand(
+	command: string,
+	args: string[],
+	options: {
+		cwd?: string;
+		env?: NodeJS.ProcessEnv;
+		allowFailure?: boolean;
+	} = {},
+): Promise<CommandResult> {
+	try {
+		const result = await execFileAsync(command, args, {
+			cwd: options.cwd,
+			env: { ...process.env, ...options.env },
+		});
+		return {
+			stdout: result.stdout.trimEnd(),
+			stderr: result.stderr?.trimEnd() ?? "",
+			exitCode: 0,
+		};
+	} catch (error) {
+		const execError = error as Error & {
+			stdout?: string;
+			stderr?: string;
+			code?: number;
+		};
+		if (!options.allowFailure) throw error;
+		return {
+			stdout: execError.stdout?.trimEnd() ?? "",
+			stderr: execError.stderr?.trimEnd() ?? "",
+			exitCode: execError.code ?? 1,
+		};
+	}
+}
+
+export async function createTempContext(
+	prefix: string,
+): Promise<TempTestContext> {
+	const root = await realpath(await mkdtemp(join(tmpdir(), `${prefix}-`)));
+	const home = join(root, "home");
+	const repo = join(root, "repo");
+	await mkdir(home, { recursive: true });
+	await mkdir(join(home, ".claude", "projects"), { recursive: true });
+	await mkdir(repo, { recursive: true });
+	return {
+		root,
+		home,
+		repo,
+		cleanup: async () => {
+			await rm(root, { recursive: true, force: true });
+		},
+	};
+}
+
+export async function initGitRepo(repo: string): Promise<void> {
+	await runCommand("git", ["init"], { cwd: repo });
+	await configureGitIdentity(repo);
+}
+
+export async function configureGitIdentity(repo: string): Promise<void> {
+	await runCommand("git", ["config", "user.name", "Test User"], { cwd: repo });
+	await runCommand("git", ["config", "user.email", "test@example.com"], {
+		cwd: repo,
+	});
+}
+
+export async function commitAll(repo: string, message: string): Promise<void> {
+	await runCommand("git", ["add", "."], { cwd: repo });
+	await runCommand("git", ["commit", "-m", message], { cwd: repo });
+}
+
+export async function currentSha(repo: string): Promise<string> {
+	const result = await runCommand("git", ["rev-parse", "HEAD"], { cwd: repo });
+	return result.stdout.trim();
+}
+
+export async function writeJsonl(
+	path: string,
+	entries: unknown[],
+): Promise<void> {
+	await mkdir(dirname(path), { recursive: true });
+	await writeFile(path, entries.map((entry) => JSON.stringify(entry)).join("\n") + "\n");
+}
+
+export function transcriptDirFor(home: string, repo: string): string {
+	return join(home, ".claude", "projects", repo.replace(/\//g, "-"));
+}
+
+export async function writeTranscript(
+	home: string,
+	repo: string,
+	sessionId: string,
+	entries: unknown[],
+): Promise<void> {
+	const dir = transcriptDirFor(home, repo);
+	await mkdir(dir, { recursive: true });
+	await writeJsonl(join(dir, `${sessionId}.jsonl`), entries);
+}
+
+export async function readJson(path: string): Promise<unknown> {
+	return JSON.parse(await readFile(path, "utf8"));
+}