claude-attribution 1.0.0

package/src/attribution/differ.ts

@@ -0,0 +1,154 @@
+/**
+ * Line attribution algorithm for claude-attribution.
+ *
+ * Core logic: compare Claude's "after" file snapshot against the "before" snapshot
+ * and the committed file content using 16-character SHA-256 line hashes to classify
+ * each committed line as AI, HUMAN, or MIXED.
+ *
+ * This module is the only place where attribution decisions are made. All other
+ * modules (commit.ts, calculate.ts) call into here and consume the results.
+ */
+import { createHash } from "crypto";
+
+export type LineAttribution = "AI" | "HUMAN" | "MIXED";
+
+export interface FileAttribution {
+	path: string;
+	ai: number;
+	human: number;
+	mixed: number;
+	total: number;
+	pctAi: number;
+}
+
+export interface AttributionResult {
+	commit: string;
+	/** Session ID from .claude/attribution-state/current-session, or null if committed outside a Claude session. */
+	session: string | null;
+	/** Git branch name at commit time, or null on detached HEAD (CI checkouts, rebases). */
+	branch: string | null;
+	timestamp: string;
+	files: FileAttribution[];
+	totals: Omit<FileAttribution, "path">;
+}
+
+/**
+ * Compute a 16-character SHA-256 hex prefix of the trimmed line content.
+ *
+ * Lines are trimmed before hashing so that equivalent code is recognized
+ * regardless of indentation differences. The 16-character prefix provides
+ * 2^64 collision resistance — sufficient for any realistic file size.
+ *
+ * This approach mirrors Docusign's internal `aidev-track` tool's ContentHasher.
+ */
+export function hashLine(line: string): string {
+	return createHash("sha256").update(line.trim()).digest("hex").slice(0, 16);
+}
+
+/**
+ * Attribute each line in `committedLines` as AI / HUMAN / MIXED.
+ *
+ * Rules:
+ *  - AI:    hash present in afterHashes but NOT in beforeHashes
+ *           → Claude wrote this line and it survived to the commit unchanged
+ *  - MIXED: hash was in afterHashes originally (positional check) but the
+ *           committed content differs from what Claude wrote at that position
+ *           → Claude wrote it, human modified it before committing
+ *  - HUMAN: everything else (existed before Claude, or written after Claude
+ *           finished without a checkpoint)
+ *
+ * Empty lines are attributed as HUMAN — they carry no signal.
+ *
+ * **Identical-line limitation**: This algorithm is set-based. If Claude and a
+ * human both write a line with the same trimmed content (e.g., a closing `}`),
+ * they produce the same hash. Lines that appear in `afterLines` but not
+ * `beforeLines` are attributed as AI regardless of who actually wrote them.
+ * This is conservative toward AI for identical content — an acceptable trade-off
+ * given that truly identical lines are indistinguishable without positional history.
+ *
+ * **MIXED detection limitation**: MIXED uses a positional index —
+ * `afterByIndex[i]` is the hash of Claude's i-th line. If a human inserts or
+ * deletes lines above position `i`, the committed file's positions shift while
+ * the after-snapshot's positions do not, causing false MIXED classifications.
+ * MIXED is therefore a "best effort" signal most accurate when human edits are
+ * small in-place tweaks (e.g., changing a value on a line Claude wrote) rather
+ * than bulk insertions or deletions that shift line numbers.
+ */
+export function attributeLines(
+	beforeLines: string[],
+	afterLines: string[],
+	committedLines: string[],
+): { attribution: LineAttribution[]; stats: FileAttribution } {
+	const beforeHashes = new Set(beforeLines.map(hashLine));
+	const afterHashes = new Set(afterLines.map(hashLine));
+	// Positional index: line index → hash (for MIXED detection)
+	const afterByIndex = afterLines.map(hashLine);
+
+	const attribution: LineAttribution[] = committedLines.map((line, i) => {
+		const hash = hashLine(line);
+
+		// Blank lines carry no signal
+		if (line.trim() === "") return "HUMAN";
+
+		if (afterHashes.has(hash) && !beforeHashes.has(hash)) {
+			return "AI";
+		}
+
+		// MIXED: Claude wrote something at this position but the human changed it
+		const afterHashAtPos = afterByIndex[i];
+		if (
+			afterHashAtPos !== undefined &&
+			!beforeHashes.has(afterHashAtPos) &&
+			hash !== afterHashAtPos
+		) {
+			return "MIXED";
+		}
+
+		return "HUMAN";
+	});
+
+	const ai = attribution.filter((a) => a === "AI").length;
+	const human = attribution.filter((a) => a === "HUMAN").length;
+	const mixed = attribution.filter((a) => a === "MIXED").length;
+	const total = committedLines.length;
+
+	return {
+		attribution,
+		stats: {
+			path: "",
+			ai,
+			human,
+			mixed,
+			total,
+			pctAi: total > 0 ? Math.round((ai / total) * 100) : 0,
+		},
+	};
+}
+
+/**
+ * Aggregate per-file attribution stats into a single totals object.
+ *
+ * Used by commit.ts to compute the commit-level summary, and by calculate.ts
+ * to compute the PR-level summary from the last-seen stats per file.
+ */
+export function aggregateTotals(
+	files: FileAttribution[],
+): Omit<FileAttribution, "path"> {
+	let ai = 0,
+		human = 0,
+		mixed = 0,
+		total = 0;
+	for (const f of files) {
+		ai += f.ai;
+		human += f.human;
+		mixed += f.mixed;
+		total += f.total;
+	}
+	return {
+		ai,
+		human,
+		mixed,
+		total,
+		pctAi: total > 0 ? Math.round((ai / total) * 100) : 0,
+	};
+}

package/src/attribution/git-notes.ts

@@ -0,0 +1,185 @@
+/**
+ * Git notes interface for claude-attribution.
+ *
+ * Attribution results are stored as JSON blobs attached to commits via
+ * `git notes --ref=refs/notes/claude-attribution`. This keeps attribution
+ * data in the git object store without modifying commit history.
+ *
+ * Notes are local by default and must be explicitly pushed/fetched:
+ *   git push origin refs/notes/claude-attribution
+ *   git fetch origin refs/notes/claude-attribution:refs/notes/claude-attribution
+ *
+ * The Faros API pipeline (ADMPLAT-9609) reads from this ref for org-wide dashboards.
+ */
+import { execFile } from "child_process";
+import { promisify } from "util";
+import type { AttributionResult } from "./differ.ts";
+
+const execFileAsync = promisify(execFile);
+const NOTES_REF = "refs/notes/claude-attribution";
+
+/** Run a shell command and return trimmed stdout. Throws on non-zero exit. */
+async function run(cmd: string, args: string[], cwd?: string): Promise<string> {
+	const { stdout } = await execFileAsync(cmd, args, { cwd });
+	return stdout.trim();
+}
+
+/** Run a shell command and return raw (untrimmed) stdout. Used for file content. */
+async function runRaw(
+	cmd: string,
+	args: string[],
+	cwd?: string,
+): Promise<string> {
+	const { stdout } = await execFileAsync(cmd, args, { cwd });
+	return stdout;
+}
+
+/**
+ * Write an AttributionResult as a git note on a commit.
+ *
+ * Runs: `git notes --ref=<NOTES_REF> add --force -m <json> <commitSha>`
+ *
+ * Uses `--force` to overwrite any existing note (e.g., from a retry after a
+ * failed hook run). Notes are stored in the git object store under NOTES_REF.
+ */
+export async function writeNote(
+	result: AttributionResult,
+	repoRoot: string,
+	commitSha = "HEAD",
+): Promise<void> {
+	const json = JSON.stringify(result, null, 2);
+	// git notes add overwrites if note already exists with --force
+	await run(
+		"git",
+		["notes", "--ref", NOTES_REF, "add", "--force", "-m", json, commitSha],
+		repoRoot,
+	);
+}
+
+/**
+ * Read the attribution note for a given commit.
+ *
+ * Runs: `git notes --ref=<NOTES_REF> show <commitSha>`
+ * Returns null if no note exists (commit was not attributed, or made before installation).
+ */
+export async function readNote(
+	repoRoot: string,
+	commitSha = "HEAD",
+): Promise<AttributionResult | null> {
+	try {
+		const output = await run(
+			"git",
+			["notes", "--ref", NOTES_REF, "show", commitSha],
+			repoRoot,
+		);
+		return JSON.parse(output) as AttributionResult;
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * List all commit SHAs that have attribution notes in the entire repository.
+ *
+ * Runs: `git notes --ref=<NOTES_REF> list`
+ * Each output line is: "<note-blob-sha> <commit-sha>"
+ *
+ * NOTE: This returns notes from ALL branches and commits, not just the current
+ * branch. Call `getBranchCommitShas()` and intersect to scope to the current branch.
+ */
+export async function listNotes(repoRoot: string): Promise<string[]> {
+	try {
+		const output = await run(
+			"git",
+			["notes", "--ref", NOTES_REF, "list"],
+			repoRoot,
+		);
+		if (!output) return [];
+		// Each line: "<note-sha> <commit-sha>"
+		return output
+			.split("\n")
+			.map((line) => line.split(" ")[1])
+			.filter((sha): sha is string => sha !== undefined && sha.length > 0);
+	} catch {
+		return [];
+	}
+}
+
+/** Get the current HEAD commit SHA. Runs: `git rev-parse HEAD` */
+export async function headSha(repoRoot: string): Promise<string> {
+	return run("git", ["rev-parse", "HEAD"], repoRoot);
+}
+
+/**
+ * Get the current branch name. Returns null on detached HEAD
+ * (e.g., CI checkouts, interactive rebases).
+ *
+ * Runs: `git symbolic-ref --short HEAD`
+ */
+export async function currentBranch(repoRoot: string): Promise<string | null> {
+	try {
+		return await run("git", ["symbolic-ref", "--short", "HEAD"], repoRoot);
+	} catch {
+		return null;
+	}
+}
+
+/**
+ * List relative paths of files changed in the HEAD commit.
+ *
+ * Uses `git diff-tree --no-commit-id -r --name-only HEAD`, which works correctly
+ * for regular commits, the initial commit (no parent), and merge commits (compares
+ * against all parents, not just HEAD~1).
+ *
+ * Binary files are included in this list; commit.ts skips them by detecting null
+ * bytes in the committed content.
+ */
+export async function filesInCommit(repoRoot: string): Promise<string[]> {
+	const output = await run(
+		"git",
+		["diff-tree", "--no-commit-id", "-r", "--name-only", "HEAD"],
+		repoRoot,
+	);
+	return output ? output.split("\n").filter(Boolean) : [];
+}
+
+/**
+ * Return the commit SHAs that are on the current branch but not yet in the
+ * remote default branch (origin/main or origin/master).
+ *
+ * Used by calculate.ts to scope `/metrics` output to the current PR's commits
+ * rather than every annotated commit across the entire repository.
+ *
+ * Runs: `git merge-base HEAD origin/main` to find the fork point, then
+ * `git log --format=%H <base>..HEAD` to list commits since.
+ * Falls back to all commits reachable from HEAD if no remote ref is found.
+ */
+export async function getBranchCommitShas(repoRoot: string): Promise<string[]> {
+	const base = await run("git", ["merge-base", "HEAD", "origin/HEAD"], repoRoot)
+		.catch(() => run("git", ["merge-base", "HEAD", "origin/main"], repoRoot))
+		.catch(() => run("git", ["merge-base", "HEAD", "origin/master"], repoRoot))
+		.catch(() => null);
+	const range = base ? `${(base as string).trim()}..HEAD` : "HEAD";
+	const out = await run("git", ["log", "--format=%H", range], repoRoot).catch(
+		() => "",
+	);
+	return out ? out.split("\n").filter(Boolean) : [];
+}
+
+/**
+ * Read the committed content of a file at HEAD as a raw string.
+ *
+ * Runs: `git show HEAD:<relPath>`
+ * Returns null for deleted files (git show exits non-zero for files not in the tree).
+ * Uses `runRaw` (untrimmed) to preserve trailing newlines in file content.
+ */
+export async function committedContent(
+	repoRoot: string,
+	relPath: string,
+): Promise<string | null> {
+	try {
+		return await runRaw("git", ["show", `HEAD:${relPath}`], repoRoot);
+	} catch {
+		return null;
+	}
+}

package/src/attribution/otel.ts

@@ -0,0 +1,233 @@
+/**
+ * OTel trace exporter — hand-crafted OTLP/HTTP over fetch, no SDK dependency.
+ *
+ * Emits two span types:
+ *   - "claude-session" (root) — created at commit time, covers the full coding session.
+ *     Attributes: session.id, git.branch, git.commit, attribution.*
+ *   - "tool_call/{toolName}" (child) — created per tool call in post-tool-use.
+ *     Attributes: tool.name, file.path (if applicable), session.id
+ *
+ * Context is persisted across short-lived hook processes to:
+ *   .claude/attribution-state/otel-context.json
+ *
+ * All OTel behavior is gated on OTEL_EXPORTER_OTLP_ENDPOINT being set.
+ * All errors are silently swallowed — never block hooks or commits.
+ *
+ * Env vars:
+ *   OTEL_EXPORTER_OTLP_ENDPOINT  — e.g. http://localhost:4318 or https://otlp.datadoghq.com
+ *   OTEL_EXPORTER_OTLP_HEADERS   — e.g. DD-Api-Key=<key>,Another-Header=value
+ *   OTEL_SERVICE_NAME             — defaults to "claude-code"
+ */
+import { readFile, writeFile, unlink } from "fs/promises";
+import { existsSync, mkdirSync } from "fs";
+import { join } from "path";
+import { randomBytes } from "crypto";
+
+export interface OtelContext {
+	traceId: string; // 32 hex chars (128-bit)
+	rootSpanId: string; // 16 hex chars (64-bit)
+	sessionId: string;
+	startTime: string; // ISO8601 — set at first pre-tool-use invocation
+	lastToolCallStart: string | null; // ISO8601 — updated each pre-tool-use
+}
+
+function contextPath(repoRoot: string): string {
+	return join(repoRoot, ".claude", "attribution-state", "otel-context.json");
+}
+
+export async function readOtelContext(
+	repoRoot: string,
+): Promise<OtelContext | null> {
+	const p = contextPath(repoRoot);
+	if (!existsSync(p)) return null;
+	try {
+		const raw = await readFile(p, "utf8");
+		return JSON.parse(raw) as OtelContext;
+	} catch {
+		return null;
+	}
+}
+
+export async function writeOtelContext(
+	repoRoot: string,
+	ctx: OtelContext,
+): Promise<void> {
+	const dir = join(repoRoot, ".claude", "attribution-state");
+	mkdirSync(dir, { recursive: true });
+	await writeFile(contextPath(repoRoot), JSON.stringify(ctx, null, 2) + "\n");
+}
+
+export async function clearOtelContext(repoRoot: string): Promise<void> {
+	try {
+		await unlink(contextPath(repoRoot));
+	} catch {
+		// Already gone — fine
+	}
+}
+
+/** Returns the OTLP endpoint, or null if OTel is disabled. */
+export function otelEndpoint(): string | null {
+	return process.env.OTEL_EXPORTER_OTLP_ENDPOINT ?? null;
+}
+
+/** Parses OTEL_EXPORTER_OTLP_HEADERS into a headers map. */
+export function otelHeaders(): Record<string, string> {
+	const raw = process.env.OTEL_EXPORTER_OTLP_HEADERS ?? "";
+	if (!raw.trim()) return {};
+	const result: Record<string, string> = {};
+	for (const pair of raw.split(",")) {
+		const idx = pair.indexOf("=");
+		if (idx === -1) continue;
+		const key = pair.slice(0, idx).trim();
+		const value = pair.slice(idx + 1).trim();
+		if (key) result[key] = value;
+	}
+	return result;
+}
+
+export function makeSpanId(): string {
+	return randomBytes(8).toString("hex");
+}
+
+export function makeTraceId(): string {
+	return randomBytes(16).toString("hex");
+}
+
+/** Convert ISO8601 string to nanoseconds string for OTLP *TimeUnixNano fields. */
+export function toNano(iso: string): string {
+	return (BigInt(new Date(iso).getTime()) * 1_000_000n).toString();
+}
+
+const SERVICE_NAME = process.env.OTEL_SERVICE_NAME ?? "claude-code";
+
+function buildResourceSpans(spans: object[]): object {
+	return {
+		resourceSpans: [
+			{
+				resource: {
+					attributes: [
+						{
+							key: "service.name",
+							value: { stringValue: SERVICE_NAME },
+						},
+					],
+				},
+				scopeSpans: [
+					{
+						scope: { name: "claude-attribution" },
+						spans,
+					},
+				],
+			},
+		],
+	};
+}
+
+function strAttr(key: string, value: string): object {
+	return { key, value: { stringValue: value } };
+}
+
+function intAttr(key: string, value: number): object {
+	return { key, value: { intValue: value } };
+}
+
+/**
+ * Build an OTLP child span for a single tool call.
+ *
+ * The span is parented to the root session span (rootSpanId).
+ * start = ctx.lastToolCallStart, end = endTime.
+ */
+export function buildToolCallSpan(
+	ctx: OtelContext,
+	toolName: string,
+	filePath: string | null,
+	endTime: string,
+): object {
+	const spanId = makeSpanId();
+	const attrs: object[] = [
+		strAttr("tool.name", toolName),
+		strAttr("session.id", ctx.sessionId),
+	];
+	if (filePath) attrs.push(strAttr("file.path", filePath));
+
+	return {
+		traceId: ctx.traceId,
+		spanId,
+		parentSpanId: ctx.rootSpanId,
+		name: `tool_call/${toolName}`,
+		kind: 1, // SPAN_KIND_INTERNAL
+		startTimeUnixNano: toNano(ctx.lastToolCallStart ?? ctx.startTime),
+		endTimeUnixNano: toNano(endTime),
+		attributes: attrs,
+		status: { code: 1 }, // STATUS_CODE_OK
+	};
+}
+
+/**
+ * Build an OTLP root span for a Claude coding session.
+ *
+ * Emitted once at commit time. Covers startTime → endTime (commit time).
+ * Carries attribution totals so APM traces correlate to code authorship.
+ */
+export function buildSessionSpan(
+	ctx: OtelContext,
+	commitSha: string,
+	branch: string | null,
+	totals: {
+		ai: number;
+		human: number;
+		mixed: number;
+		total: number;
+		pctAi: number;
+	},
+	endTime: string,
+): object {
+	const attrs: object[] = [
+		strAttr("session.id", ctx.sessionId),
+		strAttr("git.commit", commitSha),
+		intAttr("attribution.ai_lines", totals.ai),
+		intAttr("attribution.human_lines", totals.human),
+		intAttr("attribution.mixed_lines", totals.mixed),
+		intAttr("attribution.total_lines", totals.total),
+		intAttr("attribution.pct_ai", totals.pctAi),
+	];
+	if (branch) attrs.push(strAttr("git.branch", branch));
+
+	return {
+		traceId: ctx.traceId,
+		spanId: ctx.rootSpanId,
+		name: "claude-session",
+		kind: 1, // SPAN_KIND_INTERNAL
+		startTimeUnixNano: toNano(ctx.startTime),
+		endTimeUnixNano: toNano(endTime),
+		attributes: attrs,
+		status: { code: 1 }, // STATUS_CODE_OK
+	};
+}
+
+/**
+ * POST spans to the OTLP/HTTP endpoint.
+ *
+ * Uses the v1/traces path per the OTLP spec.
+ * Silent no-op on any error — never block hooks or commits.
+ */
+export async function exportOtlpSpans(
+	spans: object[],
+	endpoint: string,
+	headers: Record<string, string>,
+): Promise<void> {
+	if (spans.length === 0) return;
+	try {
+		const url = endpoint.replace(/\/$/, "") + "/v1/traces";
+		await fetch(url, {
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				...headers,
+			},
+			body: JSON.stringify(buildResourceSpans(spans)),
+		});
+	} catch {
+		// Silent — never block caller
+	}
+}

package/src/cli.ts

@@ -0,0 +1,109 @@
+/**
+ * CLI entry point for claude-attribution.
+ *
+ * Routes subcommands to existing modules via dynamic import(), which triggers
+ * auto-execution because each module calls main().catch(...) at module level.
+ * argv is shifted before delegating so sub-modules see their args at process.argv[2].
+ */
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { readFile } from "fs/promises";
+import { execFile } from "child_process";
+import { promisify } from "util";
+
+const execFileAsync = promisify(execFile);
+const [, , cmd, ...rest] = process.argv;
+
+// Shift argv so sub-modules see their expected args at process.argv[2]
+process.argv.splice(2, Infinity, ...rest);
+
+switch (cmd) {
+	case "install":
+		await import("./setup/install.ts");
+		break;
+	case "uninstall":
+		await import("./setup/uninstall.ts");
+		break;
+	case "metrics":
+		await import("./metrics/calculate.ts");
+		break;
+	case "start":
+		await import("./metrics/mark-start.ts");
+		break;
+	case "pr":
+		await import("./commands/pr.ts");
+		break;
+	case "hook": {
+		switch (rest[0]) {
+			case "pre-tool-use":
+				await import("./hooks/pre-tool-use.ts");
+				break;
+			case "post-tool-use":
+				await import("./hooks/post-tool-use.ts");
+				break;
+			case "subagent":
+				await import("./hooks/subagent.ts");
+				break;
+			case "stop":
+				await import("./hooks/stop.ts");
+				break;
+			case "post-commit":
+				await import("./attribution/commit.ts");
+				break;
+			case "pre-push":
+				try {
+					await execFileAsync("git", [
+						"push",
+						"origin",
+						"refs/notes/claude-attribution",
+					]);
+				} catch {
+					// Ignore — notes push failure must not block git push
+				}
+				process.exit(0);
+				break;
+			default:
+				console.error(`Unknown hook: ${rest[0]}`);
+				process.exit(1);
+		}
+		break;
+	}
+	case "version":
+	case "--version":
+	case "-v": {
+		const pkgPath = resolve(
+			dirname(fileURLToPath(import.meta.url)),
+			"..",
+			"package.json",
+		);
+		const pkg = JSON.parse(await readFile(pkgPath, "utf8")) as {
+			version: string;
+		};
+		console.log(pkg.version);
+		process.exit(0);
+		break;
+	}
+	case "help":
+	case "--help":
+	case "-h":
+		console.log(
+			`claude-attribution <command> [args]
+
+Commands:
+  install [repo]   Install hooks into a repo (default: current directory)
+  uninstall [repo] Remove hooks from a repo (default: current directory)
+  metrics [id]     Generate PR metrics report
+  pr [title]       Create PR with metrics embedded (--draft, --base <branch>)
+  start            Mark session start for per-ticket scoping
+  hook <name>      Run an internal hook (used by installed git hooks)
+  version          Print version
+  help             Print this help`,
+		);
+		process.exit(0);
+		break;
+	default:
+		console.error(
+			`Unknown command: ${cmd ?? "(none)"}. Run "claude-attribution help" for usage.`,
+		);
+		process.exit(1);
+}