tracehub 0.5.3 → 0.5.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,226 @@
1
+ import { isAbsolute, resolve } from "node:path";
2
+ import { isCommitCommand } from "./commitBoundary.js";
3
+ import { parseSessionLines } from "../trace/build.js";
4
+ import { formatSessionRef } from "../protocol/sessionRef.js";
5
+ // The directories a command changes to: `cd <dir>`, `pushd <dir>`, `-C <dir>`.
6
+ export function checkoutsNamed(command, home = "") {
7
+ const dirs = [];
8
+ for (const m of command.matchAll(/(?:^|[\s;&|(])(?:cd|pushd|-C)\s+("[^"]+"|'[^']+'|[^\s;&|)]+)/g)) {
9
+ let dir = m[1].replace(/^["']|["']$/g, "");
10
+ if (home && (dir === "~" || dir.startsWith("~/")))
11
+ dir = home + dir.slice(1);
12
+ if (isAbsolute(dir))
13
+ dirs.push(dir.replace(/\/+$/, ""));
14
+ }
15
+ return dirs;
16
+ }
17
+ // How far before a commit's author time a session may have started on it.
18
+ const LOOKBACK_MS = 7 * 24 * 3600_000;
19
+ // The commit's time is in whole seconds, its session's in milliseconds.
20
+ const SLACK_MS = 60_000;
21
+ export const HIGH = 7;
22
+ export const MEDIUM = 4;
23
+ // The session's events with the line each one came from; parsed one line at
24
+ // a time, as commitBoundary reads them.
25
+ export function candidateOf(ref, file, lines, opts = {}) {
26
+ const sidechain = opts.sidechain ?? false;
27
+ const events = [];
28
+ const branches = new Set();
29
+ let cwd = "";
30
+ lines.forEach((line, index) => {
31
+ if (!line.trim())
32
+ return;
33
+ const parsed = parseSessionLines(ref.agent, ref.id, [line], sidechain);
34
+ if (!cwd && parsed.cwd)
35
+ cwd = parsed.cwd;
36
+ for (const event of parsed.events)
37
+ events.push({ event, line: index });
38
+ const branch = /"gitBranch":"([^"]+)"/.exec(line)?.[1];
39
+ if (branch)
40
+ branches.add(branch);
41
+ });
42
+ return {
43
+ ref,
44
+ file,
45
+ lines,
46
+ sidechain,
47
+ parent: opts.parent,
48
+ cwd,
49
+ branches: [...branches],
50
+ events,
51
+ };
52
+ }
53
+ // When the commit was made: its committer time, unless that is a rebase or
54
+ // amend long after it was first written, whose author time stays.
55
+ export function commitTimeMs(commit) {
56
+ const late = commit.committerMs - commit.authorMs > 3600_000;
57
+ return late ? commit.authorMs : commit.committerMs;
58
+ }
59
+ // "[branch abc1234] subject": git commit's own output, naming the commit.
60
+ const COMMIT_OUTPUT = /\[[^\]\n]*?\s([0-9a-f]{7,40})\]/g;
61
+ function commitOutputNames(text, sha) {
62
+ for (const m of text.matchAll(COMMIT_OUTPUT))
63
+ if (sha.startsWith(m[1]))
64
+ return m[1];
65
+ return undefined;
66
+ }
67
+ // Lines that say something: not braces, blank or a word or two.
68
+ function telling(line) {
69
+ const t = line.trim();
70
+ return t.length >= 10 && /[A-Za-z]/.test(t);
71
+ }
72
+ // The commit's path an edit wrote, if any: an absolute path ends with it, a
73
+ // relative one does once resolved against the session's cwd.
74
+ function editedPath(path, cwd, files) {
75
+ const full = isAbsolute(path) ? path : resolve(cwd || "/", path);
76
+ return files.find((f) => full === f || full.endsWith(`/${f}`));
77
+ }
78
+ const TRUNK = new Set(["main", "master", "HEAD", "develop"]);
79
+ export function confidenceOf(score, tied) {
80
+ if (tied && score >= HIGH)
81
+ return "high";
82
+ if (score >= MEDIUM)
83
+ return "medium";
84
+ return "low";
85
+ }
86
+ // Scores one session against one commit. Undefined when the session cannot
87
+ // have made it: nothing of it was written in the week before the commit.
88
+ export function scoreMatch(commit, candidate, repo) {
89
+ const atMs = commitTimeMs(commit);
90
+ const ts = (e) => Date.parse(e.ts);
91
+ const before = candidate.events.filter(({ event }) => {
92
+ const t = ts(event);
93
+ return t <= atMs + SLACK_MS && t >= commit.authorMs - LOOKBACK_MS;
94
+ });
95
+ if (!before.length)
96
+ return undefined;
97
+ const evidence = [];
98
+ let score = 0;
99
+ let tied = false;
100
+ const short = commit.sha.slice(0, 7);
101
+ // The commit's own output, wherever it was made from.
102
+ let cut;
103
+ for (const { event, line } of candidate.events) {
104
+ if (event.kind !== "tool_result" && event.kind !== "assistant")
105
+ continue;
106
+ const named = commitOutputNames(event.text, commit.sha);
107
+ if (named) {
108
+ cut = line + 1;
109
+ break;
110
+ }
111
+ }
112
+ if (cut !== undefined) {
113
+ score += 6;
114
+ tied = true;
115
+ evidence.push(`git commit output names ${short}`);
116
+ }
117
+ const subject = commit.subject.trim();
118
+ const commitCalls = before.filter(({ event }) => event.kind === "tool_call" && isCommitCommand(event.arg));
119
+ const committed = commitCalls.some(({ event }) => subject.length >= 10 &&
120
+ event.arg.includes(subject.slice(0, 60)));
121
+ if (committed) {
122
+ score += 3;
123
+ evidence.push("a git commit call carries its subject");
124
+ }
125
+ // `cd <checkout> && git commit`, `git -C <checkout> commit`.
126
+ const committedHere = commitCalls.some(({ event }) => checkoutsNamed(event.arg, repo.home).some((dir) => repo.contains(dir)));
127
+ const edits = before.flatMap(({ event }) => event.kind === "tool_call" ? (event.edits ?? []) : []);
128
+ const inRepo = committedHere ||
129
+ (!!candidate.cwd && repo.contains(candidate.cwd)) ||
130
+ edits.some((e) => isAbsolute(e.path) && repo.contains(e.path));
131
+ if (inRepo) {
132
+ score += 2;
133
+ tied = true;
134
+ evidence.push("ran in a checkout of the repository");
135
+ }
136
+ // A push to the repository or the pull request's URL (`gh pr create`
137
+ // prints it), for a checkout removed since.
138
+ if (repo.slug) {
139
+ const slug = repo.slug.toLowerCase().replace(/[.]/g, "\\.");
140
+ const pullUrl = repo.pull
141
+ ? new RegExp(`github\\.com/${slug}/pull/${repo.pull}(?![0-9])`, "i")
142
+ : undefined;
143
+ const repoUrl = new RegExp(`github\\.com[/:]${slug}(?:\\.git)?(?![\\w.-])`, "i");
144
+ const texts = candidate.events.map(({ event }) => event.kind === "tool_call" ? event.arg : event.text);
145
+ if (pullUrl && texts.some((t) => pullUrl.test(t))) {
146
+ score += 3;
147
+ tied = true;
148
+ evidence.push(`names pull request #${repo.pull}`);
149
+ }
150
+ else if (!inRepo && texts.some((t) => repoUrl.test(t))) {
151
+ score += 1;
152
+ tied = true;
153
+ evidence.push(`names ${repo.slug} on GitHub`);
154
+ }
155
+ }
156
+ if (repo.branch &&
157
+ !TRUNK.has(repo.branch) &&
158
+ candidate.branches.includes(repo.branch)) {
159
+ score += 2;
160
+ evidence.push(`on branch ${repo.branch}`);
161
+ }
162
+ // The commit's files the session edited, and how many of the lines the
163
+ // commit adds those edits wrote.
164
+ const touched = new Set();
165
+ const written = new Set();
166
+ for (const edit of edits) {
167
+ const path = editedPath(edit.path, candidate.cwd, commit.files);
168
+ if (!path)
169
+ continue;
170
+ touched.add(path);
171
+ for (const line of edit.added)
172
+ written.add(line.trim());
173
+ }
174
+ if (touched.size) {
175
+ score += Math.min(3, touched.size);
176
+ evidence.push(`edited ${touched.size}/${commit.files.length} of its files`);
177
+ }
178
+ const wanted = new Set([...commit.added.values()]
179
+ .flat()
180
+ .filter(telling)
181
+ .map((l) => l.trim()));
182
+ let share = 0;
183
+ if (wanted.size && written.size) {
184
+ const hit = [...wanted].filter((l) => written.has(l)).length;
185
+ share = hit / wanted.size;
186
+ if (hit) {
187
+ score += share >= 0.5 ? 3 : share >= 0.2 ? 2 : 1;
188
+ evidence.push(`wrote ${Math.round(share * 100)}% of its added lines`);
189
+ }
190
+ }
191
+ if (!tied && touched.size && (share >= 0.5 || (committed && share > 0))) {
192
+ tied = true;
193
+ }
194
+ if (cut === undefined) {
195
+ const last = before.at(-1);
196
+ cut = last.line + 1;
197
+ }
198
+ return {
199
+ session: formatSessionRef(candidate.ref),
200
+ score,
201
+ confidence: confidenceOf(score, tied),
202
+ tied,
203
+ evidence,
204
+ cut,
205
+ };
206
+ }
207
+ // Whether a match is uploaded: a tied session of high confidence, or of
208
+ // medium when the caller named the session.
209
+ export function chosen(match, named = false) {
210
+ if (!match.tied)
211
+ return false;
212
+ return (match.confidence === "high" || (named && match.confidence === "medium"));
213
+ }
214
+ // The matches of a commit, best first, without a subagent whose session is
215
+ // chosen too (its run is in that session's trace).
216
+ export function rankMatches(commit, candidates, repo) {
217
+ const scored = candidates
218
+ .map((candidate) => ({
219
+ candidate,
220
+ match: scoreMatch(commit, candidate, repo),
221
+ }))
222
+ .filter((s) => s.match !== undefined && s.match.score > 0)
223
+ .sort((a, b) => b.match.score - a.match.score);
224
+ const parents = new Set(scored.filter((s) => chosen(s.match)).map((s) => s.match.session));
225
+ return scored.filter((s) => !s.candidate.parent || !parents.has(s.candidate.parent));
226
+ }
@@ -94,7 +94,8 @@ export function claudeCwd(file) {
94
94
  }
95
95
  return "";
96
96
  }
97
- // ~/.claude/projects/<encoded cwd>/<session id>.jsonl
97
+ // ~/.claude/projects/<encoded cwd>/<session id>.jsonl, or under
98
+ // $CLAUDE_CONFIG_DIR/projects.
98
99
  function listClaudeFiles(repoRoot) {
99
100
  const dir = join(claudeProjectsDir(), encodeClaudeCwd(repoRoot));
100
101
  return listDir(dir)
@@ -211,8 +212,7 @@ function dayKey(ms) {
211
212
  // ~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-<time>-<session id>.jsonl, for
212
213
  // the files written to since sinceMs. A session is filed under the day it
213
214
  // started, so the day before is walked too.
214
- export function* walkCodexFiles(sinceMs) {
215
- const base = codexSessionsDir();
215
+ export function* walkCodexFiles(sinceMs, base = codexSessionsDir()) {
216
216
  const firstDay = dayKey(Math.max(0, sinceMs - DAY_MS));
217
217
  for (const year of listDir(base)) {
218
218
  for (const month of listDir(join(base, year))) {
@@ -5,6 +5,13 @@ export const ENV_SESSION_ID = "TRACEHUB_ID";
5
5
  export const ENV_DISABLE = "TRACEHUB";
6
6
  // Context refs for every session of a commit: `<provider>:<id>[,…]`.
7
7
  export const ENV_CONTEXT = "TRACEHUB_CONTEXT";
8
+ // Set by the agents themselves: where they keep their sessions, and the
9
+ // session a command of theirs runs in (a Claude Code subagent's commands
10
+ // carry its parent's).
11
+ export const ENV_CLAUDE_CONFIG_DIR = "CLAUDE_CONFIG_DIR";
12
+ export const ENV_CODEX_HOME = "CODEX_HOME";
13
+ export const ENV_CLAUDE_SESSION = "CLAUDE_CODE_SESSION_ID";
14
+ export const ENV_CODEX_THREAD = "CODEX_THREAD_ID";
8
15
  export const ENV_TEST = "TRACEHUB_TEST";
9
16
  // Under ENV_TEST only: how long a push waits for its upload, in ms.
10
17
  export const ENV_TEST_PUSH_BUDGET = "TRACEHUB_TEST_PUSH_BUDGET_MS";
@@ -14,20 +21,26 @@ export const ENV_TEST_PUSH_BUDGET = "TRACEHUB_TEST_PUSH_BUDGET_MS";
14
21
  function override(name) {
15
22
  const value = process.env[name];
16
23
  if (value === undefined &&
17
- (process.env[ENV_TEST] !== undefined ||
18
- process.env["NODE_TEST_CONTEXT"] !== undefined)) {
19
- throw new Error(`${name} must be set while ${ENV_TEST} or NODE_TEST_CONTEXT is`);
24
+ (process.env[ENV_TEST] !== undefined || process.env["VITEST"] !== undefined)) {
25
+ throw new Error(`${name} must be set while ${ENV_TEST} or VITEST is`);
20
26
  }
21
27
  return value;
22
28
  }
23
29
  export function home() {
24
30
  return override("TRACEHUB_HOME") ?? homedir();
25
31
  }
32
+ // The directory an agent keeps its state in: the one its environment
33
+ // variable names, as the agent itself reads it, else its default. A Claude
34
+ // Code with CLAUDE_CONFIG_DIR set (an app running one per account) writes
35
+ // nothing to ~/.claude, so only its own directory is read.
36
+ function agentDir(variable, fallback) {
37
+ return process.env[variable] || join(home(), fallback);
38
+ }
26
39
  export function claudeProjectsDir() {
27
- return join(home(), ".claude", "projects");
40
+ return join(agentDir(ENV_CLAUDE_CONFIG_DIR, ".claude"), "projects");
28
41
  }
29
42
  export function codexSessionsDir() {
30
- return join(home(), ".codex", "sessions");
43
+ return join(agentDir(ENV_CODEX_HOME, ".codex"), "sessions");
31
44
  }
32
45
  // OpenCode keeps every session in one SQLite database.
33
46
  export function opencodeDb() {
@@ -55,7 +55,9 @@ export function listSubagents(ref, sessionFile) {
55
55
  return listClaudeSubagents(sessionFile);
56
56
  if (ref.agent === "opencode")
57
57
  return listOpencodeSubagents(ref.id);
58
- const files = [...walkCodexFiles(0)].map(({ file }) => ({
58
+ // The sessions directory the parent's file is in, <base>/yyyy/mm/dd/.
59
+ const base = dirname(dirname(dirname(dirname(sessionFile))));
60
+ const files = [...walkCodexFiles(0, base)].map(({ file }) => ({
59
61
  file,
60
62
  firstLine: firstLineOf(file),
61
63
  }));
@@ -18,7 +18,3 @@ export function parseSessionName(name) {
18
18
  export function sessionName(ref) {
19
19
  return `${ref.agent}-${ref.id}.jsonl`;
20
20
  }
21
- export function uniqueRefs(refs) {
22
- const byKey = new Map(refs.map((ref) => [formatSessionRef(ref), ref]));
23
- return [...byKey.values()];
24
- }
@@ -84,7 +84,9 @@ const DETECTORS = [
84
84
  return out;
85
85
  },
86
86
  },
87
- keepPrefix("url_credentials", /(\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@"'`]+:)[^\s/@"'`]+(?=@)/gi),
87
+ // The password runs to the last `@` (it may hold `/` and `@`), unless it
88
+ // is a port and path (`host:3000/@user`).
89
+ keepPrefix("url_credentials", /(\b[a-z][a-z0-9+.-]*:\/\/[^\s/:@"'`]+:)(?!\d{1,5}[/?#])[^\s"'`]+(?=@)/gi),
88
90
  whole("pem_block", /-----BEGIN [A-Z ]+-----[\s\S]*?-----END [A-Z ]+-----/g),
89
91
  whole("pem_block", /-----BEGIN [A-Z ]+-----[\s\S]*$/gm),
90
92
  whole("openai_key", /\bsk-[A-Za-z0-9_-]{8,}\b/g),
@@ -104,9 +106,10 @@ const DETECTORS = [
104
106
  keepPrefix("authorization_header", /(\bauthorization\s*[:=]\s*)(?:(?:bearer|basic|token)\s+)?\S+/gi),
105
107
  keepPrefix("bearer_token", /(\bBearer\s+)[A-Za-z0-9._~+/=-]{8,}/g),
106
108
  keepPrefix("basic_auth", /(\bBasic\s+)[A-Za-z0-9+/]{8,}={0,2}/g),
107
- keepPrefix("keyed_assignment", /(\b(?:(?:[A-Za-z0-9]+[_-])+(?:key|token|secret|password|passwd|pwd)|password|passwd|pwd|secret|token|credentials?)\s*[=:]\s*["']?)[^\s"'&,;]+/gi),
108
- keepPrefix("keyed_assignment", /(\b(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|PWD)\s*[=:]\s*["']?)[^\s"'&,;]+/g),
109
- keepPrefix("json_secret_assignment", /(\b(?:[a-z0-9_\-]*(?:password|passwd|secret|token|api_key|apikey|private_key|credentials?))["']\s*:\s*["'])[^"'\r\n]+/gi),
109
+ // A quoted value runs to its closing quote, spaces, commas and all.
110
+ keepPrefix("keyed_assignment", /(\b(?:(?:[A-Za-z0-9]+[_-])+(?:key|token|secret|password|passwd|pwd)|password|passwd|pwd|secret|token|credentials?)\s*[=:]\s*["']?)(?:(?<=")(?:\\.|[^"\\\r\n])+|(?<=')(?:\\.|[^'\\\r\n])+|[^\s"'&,;]+)/gi),
111
+ keepPrefix("keyed_assignment", /(\b(?:KEY|TOKEN|SECRET|PASSWORD|PASSWD|PWD)\s*[=:]\s*["']?)(?:(?<=")(?:\\.|[^"\\\r\n])+|(?<=')(?:\\.|[^'\\\r\n])+|[^\s"'&,;]+)/g),
112
+ keepPrefix("json_secret_assignment", /(\b(?:[a-z0-9_\-]*(?:password|passwd|secret|token|api_key|apikey|private_key|credentials?))["']\s*:\s*["'])(?:(?<=")(?:\\.|[^"\\\r\n])+|(?<=')(?:\\.|[^'\\\r\n])+)/gi),
110
113
  whole("long_hex", /\b[0-9a-fA-F]{64,}\b/g),
111
114
  {
112
115
  type: "keyed_hex",
@@ -222,14 +222,18 @@ export function buildTrace(input, opts = {}) {
222
222
  // subagents work in a worktree) shares nothing of its own: only the
223
223
  // subagent runs that changed the repository's files.
224
224
  // A subagent found by what it did in the repository counts as inside it,
225
- // whatever cwd its lines carry over from its parent.
226
- const outside = !sidechain && !ownCheckout(cwd);
225
+ // whatever cwd its lines carry over from its parent, and so does a
226
+ // session that made the commit itself (`cd <checkout> && git commit`).
227
+ const outside = !sidechain && !input.committer && !ownCheckout(cwd);
227
228
  if (outside) {
228
229
  turns = turns.map((turn) => ({
229
230
  at: turn.at,
230
231
  messages: [],
231
232
  changes: [],
232
- runs: turn.runs.map((run) => changed(run.turns) ? run : { label: run.label, turns: [] }),
233
+ runs: turn.runs.map((run) =>
234
+ // An unrelated run keeps its place (turn paths count runs), not
235
+ // its label: the label is the coordinator's own description.
236
+ changed(run.turns) ? run : { label: "", turns: [] }),
233
237
  }));
234
238
  ctx.written = ctx.written.filter((w) => w.turn.includes("."));
235
239
  if (!turns.some((turn) => turn.runs.some((run) => run.turns.length)))
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tracehub",
3
- "version": "0.5.3",
3
+ "version": "0.5.5",
4
4
  "description": "Attach coding-agent sessions (Claude Code, Codex, OpenCode) to git commits and pull requests, redacted.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -19,15 +19,18 @@
19
19
  "typecheck": "tsc --noEmit -p tsconfig.test.json",
20
20
  "format": "oxfmt --check",
21
21
  "format:fix": "oxfmt",
22
- "test": "tsc -p tsconfig.test.json && node --test --import ./dist-test/test/support/testEnv.js dist-test/test/*.test.js",
22
+ "test": "tsc -p tsconfig.test.json && vitest run",
23
+ "test:coverage": "tsc -p tsconfig.test.json && vitest run --coverage --coverage.reporter=text --coverage.reporter=html --coverage.reporter=json-summary",
23
24
  "prepack": "npm run build",
24
25
  "docs:install": "pnpm --dir docs install",
25
26
  "docs:dev": "pnpm --dir docs dev"
26
27
  },
27
28
  "devDependencies": {
28
29
  "@types/node": "^26.6.6",
30
+ "@vitest/coverage-v8": "^5.0.5",
29
31
  "oxfmt": "^0.74.0",
30
- "typescript": "^7.0.2"
32
+ "typescript": "^7.0.2",
33
+ "vitest": "^5.0.5"
31
34
  },
32
35
  "repository": {
33
36
  "type": "git",
@@ -42,5 +45,15 @@
42
45
  },
43
46
  "dependencies": {
44
47
  "@clack/prompts": "^1.8.1"
48
+ },
49
+ "allowScripts": {
50
+ "fsevents@2.3.3": true
51
+ },
52
+ "devEngines": {
53
+ "packageManager": {
54
+ "name": "npm",
55
+ "version": ">=11.17.0",
56
+ "onFail": "error"
57
+ }
45
58
  }
46
59
  }