Git for the intent behind agent-written code. Records what your coding agent decided and why, and links every commit to it.
JavaScript ai-codingclaudeclaude-codeclaude-code-pluginclicoding-agentsdeveloper-toolsgitllmtypescript
feat(files): trace which conversations touched a file
Eren0622bd5f8933
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex ded75c1..6fb8e40 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -6,6 +6,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- File history: a Files view on the map lists every file a recorded message touched — the paths the agent listed on the message plus the files of its commits read from git at build time — most recently touched first with a count. Opening a file lists the messages that changed it, newest first, with time, short hash, `mN`, the branch and the commits; clicking one opens that message in place on the graph and centres the view on it. `codelineage log --file <path>` prints the same list from the CLI (`--json` prints the model), and a path git knows but no record touched says so plainly.- Lineage search: `codelineage search <text> [dir]` scans message titles, notes and decisions, branch summaries, session titles and status, and the stored conversation (never tool output) with a case- and accent-insensitive matcher that folds Turkish letters both ways (`I`, `İ` and `ı` all match; `ş`, `ğ`, `ç`, `ö`, `ü` match their plain forms). Each hit prints its short hash, `mN`, time, session, where it matched (title / branch / conversation / session) and a one-line excerpt, newest first; `-n <count>`, `--session <id|prefix>` and `--json` are there too. The map gets a search box in the page head: Ctrl/Cmd+F focuses it (a second press opens the browser's own find), matching messages are highlighted and their sessions open, a `3 / 12` counter with ↑/↓ (Enter / Shift+Enter) steps through the hits, Esc clears, and pasting a message hash (or a unique `h…` prefix) jumps to it like `show`. The session-start context and the lineage skill now point at `search` for "where did we discuss…".- Settings modal on every page: a ⚙ Settings button in the top bar of both the project map and the panel opens the same dialog (close with ×, Esc or a click outside; focus moves into the dialog and back to the button), with one help line per setting and a "Saved" line per change. The panel's old settings box at the bottom is gone. The dialog reads the current values with `GET /api/config` (same Host / Origin / token checks as the write, and only the editable keys), and the local server now puts its per-start token in map pages too, so a map built before a change still shows the current value; over `file://` it shows the values embedded at build time read-only with a hint to use `codelineage open` or `codelineage config set`.diff --git a/packages/cli/src/commands/build.ts b/packages/cli/src/commands/build.tsindex a5af873..803a422 100644--- a/packages/cli/src/commands/build.ts+++ b/packages/cli/src/commands/build.ts@@ -1,4 +1,10 @@-import { ensureConversationGitignore, findGitRoot, readCommitSubjects } from "../git.js";+import {+ ensureConversationGitignore,+ findGitRoot,+ projectFiles,+ readCommitFiles,+ readCommitSubjects,+} from "../git.js";import { CliError, type Io } from "../io.js";import {hashTurns,@@ -21,6 +27,7 @@ import { projectPaths } from "../store/paths.js";import { resolveProjectRoot } from "../store/root.js";import { loadAllSessions, loadConfig, loadProject } from "../store/stores.js";import { type ChatTurn, displayTurn, excerpt, readConversation } from "../transcript.js";+import { buildFileHistory, modelSessions } from "../view/files.js";import { buildViewModel, embedViewModel } from "../view/lineage.js";import type { LineageViewModel, ViewChatTurn, ViewPendingMessage } from "../view/model.js";import {@@ -191,23 +198,33 @@ async function readTranscriptViews(return { chats, pending, sessions: prepared, unrecorded };}+interface CommitInfo {+ /** Subject per recorded hash, for the tags and the drill-down (Story 8.8). */+ subjects: Map<string, string>;+ /** Project-relative files per recorded hash, for the file history (Story 8.15). */+ files: Map<string, string[]>;+}+/**- * Every commit hash the records list, with its subject read from git, so the- * message rows can show commit tags and the drill-down can name them (Story- * 8.8). A project outside git, or a commit git no longer knows, only means- * fewer subjects; the build never fails for it.+ * Every commit hash the records list, with its subject and the files it changed+ * read from git. A project outside git, or a commit git no longer knows, only+ * means fewer tags and fewer files; the build never fails for it.*/-async function commitSubjects(root: string, sessions: Session[]): Promise<Map<string, string>> {+async function commitInfo(root: string, sessions: Session[]): Promise<CommitInfo> {const hashes = new Set<string>();for (const session of sessions) {for (const node of session.nodes) {for (const hash of node.commits ?? []) hashes.add(hash);}}- if (hashes.size === 0) return new Map();+ if (hashes.size === 0) return { subjects: new Map(), files: new Map() };const gitRoot = await findGitRoot(root);- if (gitRoot === undefined) return new Map();- return await readCommitSubjects(gitRoot, hashes);+ if (gitRoot === undefined) return { subjects: new Map(), files: new Map() };+ const [subjects, files] = await Promise.all([+ readCommitSubjects(gitRoot, hashes),+ readCommitFiles(gitRoot, hashes),+ ]);+ return { subjects, files: projectFiles(gitRoot, root, files) };}/**@@ -252,7 +269,7 @@ export async function buildProject(opts: BuildOptions): Promise<LineageViewModelconst transcripts = await collectTranscripts(io.env);const config = await loadConfig(io.env);const views = await readTranscriptViews(sessions, transcripts, root, io);- const subjects = await commitSubjects(root, views.sessions);+ const commits = await commitInfo(root, views.sessions);const built = buildViewModel({project: project.data,sessions: views.sessions,@@ -261,7 +278,7 @@ export async function buildProject(opts: BuildOptions): Promise<LineageViewModeltranscripts: new Set(transcripts.keys()),chats: views.chats,pending: views.pending,- commitSubjects: subjects,+ commitSubjects: commits.subjects,// Over `file://` the settings modal shows these; a server page reads the// live values instead, so a map built before a change still agrees.settings: panelSettings(config),@@ -270,6 +287,9 @@ export async function buildProject(opts: BuildOptions): Promise<LineageViewModelunrecorded: config.sessionEndCatchUp ? undefined : views.unrecorded,});built.switcher = switcher;+ // The files view (8.15) unions each message's own files with the files of+ // its commits, so a message the agent listed no paths for still lands.+ built.files = buildFileHistory(modelSessions(built), commits.files);// The skill already avoids secrets; this is the safety net before rendering.const redacted = redactDeep(built);if (redacted.count > 0)diff --git a/packages/cli/src/commands/log.ts b/packages/cli/src/commands/log.tsindex 6fad674..74c6cd8 100644--- a/packages/cli/src/commands/log.ts+++ b/packages/cli/src/commands/log.ts@@ -1,12 +1,13 @@-import { readCommitSubjects } from "../git.js";+import { findGitRoot, projectFiles, readCommitFiles, readCommitSubjects } from "../git.js";import { CliError, type Io } from "../io.js";import { readSessionMessages, type SessionMessage, upgradeSessionIds } from "../messages.js";import type { LineageNode, Session } from "../schema/session.js";import { applyEvents, readEvents } from "../store/events.js";import { resolveProjectRoot } from "../store/root.js";import { loadAllSessions, loadProject } from "../store/stores.js";+import { buildFileHistory, type FileSourceSession } from "../view/files.js";import { buildMessages } from "../view/lineage.js";-import type { ViewNode } from "../view/model.js";+import type { ViewFile, ViewNode } from "../view/model.js";/*** `codelineage log` and `codelineage show` (Story 8.10): the CLI's read verbs,@@ -645,3 +646,75 @@ export async function log(opts: LogCommandOptions): Promise<LogModel> {for (const line of formatLog(model, opts.branchesOnly === true)) opts.io.out(line);return model;}++/**+ * `./src\a.ts` and `src/a.ts` name the same file; the model stores forward-slash+ * paths without a leading `./` (Story 8.15).+ */+export function normalizeFilePath(file: string): string {+ return file+ .replace(/\\/g, "/")+ .replace(/^(\.\/)+/, "")+ .replace(/\/+$/, "");+}++/** The plain-text file history: one line per message, newest first. */+export function formatFileHistory(file: ViewFile): string[] {+ const count = `${file.count} message${file.count === 1 ? "" : "s"}`;+ const lines = [`${file.path} ${count} (newest first)`];+ for (const hit of file.hits) {+ const parts = [+ ` ${stamp(hit.at)} ${shortHash(hit.messageId)} ${hit.label} ${oneLine(hit.title)}`,+ ];+ parts.push(` · ${oneLine(hit.sessionTitle)}`);+ if (hit.branch !== undefined) parts.push(` ╭ ${oneLine(hit.branch)}`);+ if (hit.commits.length > 0)+ parts.push(` [${hit.commits.map((hash) => hash.slice(0, 7)).join(" ")}]`);+ lines.push(parts.join(""));+ }+ return lines;+}++export interface FileLogOptions {+ dir: string;+ /** The file whose history to print, relative to the project. */+ file: string;+ io: Io;+ json?: boolean;+}++/**+ * `codelineage log --file <path>`: the recorded messages that touched a file,+ * newest first — the CLI side of the map's files view (Story 8.15). Files come+ * from each message's own `files` plus the files of its commits read from git.+ */+export async function logFile(opts: FileLogOptions): Promise<ViewFile | null> {+ const root = await openProject(opts.dir);+ const sessions = await loadEffectiveSessions(root, opts.io);+ const hashes = new Set(+ sessions.flatMap((entry) => entry.messages.flatMap((message) => message.commits ?? [])),+ );+ let commitFiles: Map<string, string[]> = new Map();+ if (hashes.size > 0) {+ const gitRoot = await findGitRoot(root);+ if (gitRoot !== undefined)+ commitFiles = projectFiles(gitRoot, root, await readCommitFiles(gitRoot, hashes));+ }+ const sources: FileSourceSession[] = sessions.map(({ session, messages }) => ({+ sessionId: session.sessionId,+ title: session.title,+ messages,+ }));+ const wanted = normalizeFilePath(opts.file);+ const found = buildFileHistory(sources, commitFiles).find((file) => file.path === wanted);+ if (found === undefined) {+ opts.io.out(`No recorded message touched ${opts.file}.`);+ return null;+ }+ if (opts.json === true) {+ opts.io.out(JSON.stringify(found, null, 2));+ return found;+ }+ for (const line of formatFileHistory(found)) opts.io.out(line);+ return found;+}diff --git a/packages/cli/src/git.ts b/packages/cli/src/git.tsindex fa97cf8..d25c2e5 100644--- a/packages/cli/src/git.ts+++ b/packages/cli/src/git.ts@@ -1,6 +1,6 @@import { execFile } from "node:child_process";import { readFile, stat } from "node:fs/promises";-import { dirname, join } from "node:path";+import { dirname, isAbsolute, join, relative, sep } from "node:path";import { promisify } from "node:util";import { atomicWrite } from "./store/fs.js";@@ -138,6 +138,115 @@ export async function readCommitSubjects(return out;}+/** One commit with the files it changed, as `git log --name-only` printed it. */+interface CommitFiles {+ full: string;+ short: string;+ files: string[];+}++/**+ * Parses `%x00%H --name-only` output: a NUL-prefixed hash line starts a commit,+ * the file lines after it belong to that commit until the next hash line.+ */+function parseFileSections(stdout: string): CommitFiles[] {+ const out: CommitFiles[] = [];+ let current: CommitFiles | null = null;+ for (const line of stdout.split("\n")) {+ if (line.startsWith("\0")) {+ const full = line.slice(1).trim();+ current = /^[0-9a-f]{40}$/.test(full) ? { full, short: "", files: [] } : null;+ if (current) out.push(current);+ continue;+ }+ const file = line.trim();+ if (current !== null && file !== "") current.files.push(file);+ }+ return out;+}++/**+ * The files each given commit changed, keyed by the hash the record holds+ * (Story 8.15: the map's file history). Paths are relative to the repository+ * root. Missing commits and a missing git binary only drop entries, never fail+ * the build — same policy as `readCommitSubjects`.+ */+export async function readCommitFiles(+ root: string,+ hashes: Iterable<string>,+): Promise<Map<string, string[]>> {+ const wanted = [...new Set(hashes)];+ const out = new Map<string, string[]>();+ if (wanted.length === 0) return out;++ const remember = (entries: CommitFiles[]): void => {+ for (const hash of wanted) {+ const commit = entries.find(+ (entry) => entry.full.startsWith(hash) || hash.startsWith(commitShort(entry)),+ );+ if (commit && !out.has(hash)) out.set(hash, commit.files);+ }+ };++ try {+ const { stdout } = await exec("git", [+ "-C",+ root,+ "log",+ "--no-walk=unsorted",+ "--format=%x00%H",+ "--name-only",+ ...wanted,+ ]);+ remember(parseFileSections(stdout));+ } catch {+ for (const hash of wanted) {+ try {+ const { stdout } = await exec("git", [+ "-C",+ root,+ "show",+ "--format=%x00%H",+ "--name-only",+ hash,+ ]);+ remember(parseFileSections(stdout));+ } catch {+ // gone from this repository (rebased away, or another checkout)+ }+ }+ }+ return out;+}++/** A commit's short hash, computed when git printed only the full one. */+function commitShort(commit: CommitFiles): string {+ return commit.short === "" ? commit.full.slice(0, 7) : commit.short;+}++/**+ * Rebases repository-relative file paths onto the project root and drops the+ * files outside it, so the map compares commit files with the paths the records+ * hold (Story 8.15). A project at the repository root passes through unchanged.+ */+export function projectFiles(+ gitRoot: string,+ root: string,+ files: ReadonlyMap<string, string[]>,+): Map<string, string[]> {+ if (gitRoot === root) return new Map(files);+ const out = new Map<string, string[]>();+ for (const [hash, list] of files) {+ const kept = list.flatMap((file) => {+ const rel = relative(root, join(gitRoot, file));+ if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) return [];+ return [rel.split(sep).join("/")];+ });+ if (kept.length > 0) out.set(hash, kept);+ }+ return out;+}+/*** Full hashes git blames for `file`; `file:line` asks about one line and a bare* file means every commit that touched it (Story 8.8). `file` is relative todiff --git a/packages/cli/src/program.ts b/packages/cli/src/program.tsindex 1ccc691..cf63b00 100644--- a/packages/cli/src/program.ts+++ b/packages/cli/src/program.ts@@ -12,7 +12,7 @@ import {} from "./commands/config.js";import { epochAdd } from "./commands/epoch.js";import { type InitOptions, init } from "./commands/init.js";-import { formatShow, log, show } from "./commands/log.js";+import { formatShow, log, logFile, show } from "./commands/log.js";import { migrateIds } from "./commands/migrate.js";import { openPanel, openProject } from "./commands/open.js";import { search } from "./commands/search.js";@@ -118,6 +118,7 @@ export function createProgram(makeIo: IoFactory = processIo, deps: ProgramDeps =.option("--session <id>", "only this session (id or prefix)").option("-n, --number <count>", "at most this many messages", positiveCount).option("--branches", "only the branch summaries (the compressed view)")+ .option("--file <path>", "only messages that touched this file (its history)").option("--json", "print JSON instead of text").action(run(@@ -128,11 +129,22 @@ export function createProgram(makeIo: IoFactory = processIo, deps: ProgramDeps =session?: string;number?: number;branches?: boolean;+ file?: string;json?: boolean;},) => {+ const target = opts.dir ?? dir;+ if (opts.file !== undefined) {+ await logFile({+ dir: target,+ file: opts.file,+ io: makeIo(false),+ json: opts.json === true,+ });+ return;+ }await log({- dir: opts.dir ?? dir,+ dir: target,io: makeIo(false),session: opts.session,limit: opts.number,diff --git a/packages/cli/src/view/files.ts b/packages/cli/src/view/files.tsnew file mode 100644index 0000000..f7d8c5d--- /dev/null+++ b/packages/cli/src/view/files.ts@@ -0,0 +1,101 @@+import type { LineageViewModel, ViewFile, ViewFileHit, ViewNode } from "./model.js";++/**+ * File history (Story 8.15): which recorded messages touched a file, built from+ * the `files` the agent listed on a message plus the files of the message's+ * commits read from git at build time. `codelineage log --file` and the map's+ * files view read the same model.+ */++/** The part of a session the file history needs; a `ViewSession` fits as is. */+export interface FileSourceSession {+ sessionId: string;+ /** The session's title; a session without one falls back to its id. */+ title: string;+ messages: readonly ViewNode[];+}++/** Parsed time, with `-Infinity` for an absent or rejected value. */+function timeOf(at: string | undefined): number {+ if (at === undefined) return Number.NEGATIVE_INFINITY;+ const time = Date.parse(at);+ return Number.isNaN(time) ? Number.NEGATIVE_INFINITY : time;+}++/** Newest first; the ids keep equal timestamps deterministic. */+function byNewest(a: ViewFileHit, b: ViewFileHit): number {+ return (+ timeOf(b.at) - timeOf(a.at) ||+ a.sessionId.localeCompare(b.sessionId) ||+ a.messageId.localeCompare(b.messageId)+ );+}++/**+ * `commitFiles` maps each recorded commit hash to the repository files it+ * changed. A commit hash git could not read keeps the message's own commits+ * listed (the record still knows them); a commit git does know contributes only+ * the paths it actually touched.+ */+export function buildFileHistory(+ sessions: readonly FileSourceSession[],+ commitFiles: ReadonlyMap<string, string[]> = new Map(),+): ViewFile[] {+ const byPath = new Map<string, ViewFileHit[]>();++ for (const session of sessions) {+ const sessionTitle = session.title.trim() === "" ? session.sessionId : session.title;+ // The branch a message sits in: the last branch summary that started at or+ // before it (same rule as `log` and the map's lanes).+ let branchTitle: string | undefined;+ for (const message of session.messages) {+ if (message.branch !== undefined) branchTitle = message.branch.title;+ const commits = message.commits ?? [];+ const fromCommits = new Map<string, string[]>();+ for (const hash of commits) {+ for (const path of commitFiles.get(hash) ?? []) {+ const list = fromCommits.get(path) ?? [];+ list.push(hash);+ fromCommits.set(path, list);+ }+ }+ const paths = new Set<string>([...(message.files ?? []), ...fromCommits.keys()]);+ // A commit git does not know cannot say which files it touched, so it stays+ // listed for every file of the message; a known commit only for its own.+ const unknown = commits.filter((hash) => !commitFiles.has(hash));+ for (const path of paths) {+ const touching = [...(fromCommits.get(path) ?? []), ...unknown];+ const hit: ViewFileHit = {+ sessionId: session.sessionId,+ sessionTitle,+ messageId: message.id,+ label: message.label ?? message.id,+ ...(message.at === undefined ? {} : { at: message.at }),+ title: message.title,+ ...(branchTitle === undefined ? {} : { branch: branchTitle }),+ commits: [...new Set(touching)],+ };+ const list = byPath.get(path) ?? [];+ list.push(hit);+ byPath.set(path, list);+ }+ }+ }++ const files: ViewFile[] = [...byPath].map(([path, hits]) => {+ hits.sort(byNewest);+ const newest = hits[0];+ return {+ path,+ hits,+ count: hits.length,+ ...(newest?.at === undefined ? {} : { lastAt: newest.at }),+ };+ });+ return files.sort((a, b) => timeOf(b.lastAt) - timeOf(a.lastAt) || a.path.localeCompare(b.path));+}++/** Every session of a built page, epoch order and then the unassigned ones. */+export function modelSessions(model: LineageViewModel): FileSourceSession[] {+ return [...model.epochs.flatMap((epoch) => epoch.sessions), ...model.unassigned];+}diff --git a/packages/cli/src/view/model.ts b/packages/cli/src/view/model.tsindex 5659a89..a1a9419 100644--- a/packages/cli/src/view/model.ts+++ b/packages/cli/src/view/model.ts@@ -233,6 +233,12 @@ export interface LineageViewModel {* have no switcher.*/switcher?: ViewSwitcherProject[];+ /**+ * Which conversations touched which file (Story 8.15), most recently touched+ * first: the union of each message's `files` and the files of its commits,+ * read from git at build time. Absent on pages built before 8.15.+ */+ files?: ViewFile[];/*** Settings embedded at build time (Story 8.13). The settings modal shows them* read-only over `file://`; over the local server it reads the live values@@ -241,6 +247,36 @@ export interface LineageViewModel {settings?: PanelSettings;}+/**+ * One message that touched a file (Story 8.15): the file view's row on the map+ * and what `codelineage log --file` prints. `commits` are the commits that+ * touched this file; a commit git no longer knows leaves an empty list.+ */+export interface ViewFileHit {+ sessionId: string;+ /** The session's title, or its id when the record has none yet. */+ sessionTitle: string;+ messageId: string;+ /** The message's `mN` label. */+ label: string;+ at?: string;+ title: string;+ /** The branch the message sits in, when a branch summary starts at or before it. */+ branch?: string;+ commits: string[];+}++/** A file recorded messages touched, most recently touched first. */+export interface ViewFile {+ /** Project-relative path (`src/app.ts`). */+ path: string;+ /** Messages that touched it, newest first. */+ hits: ViewFileHit[];+ count: number;+ /** Time of the newest hit. */+ lastAt?: string;+}+/** One project card in the global panel. */export interface PanelProject {name: string;diff --git a/packages/cli/test/build.test.ts b/packages/cli/test/build.test.tsindex 2941698..3ca8aeb 100644--- a/packages/cli/test/build.test.ts+++ b/packages/cli/test/build.test.ts@@ -504,6 +504,53 @@ describe("codelineage build", () => {expect(embedded(html)).toEqual(model);});+ it("builds the file history from message files and the files of their commits", async () => {+ await run("git", ["-C", root, "init", "-q"]);+ await run("git", ["-C", root, "config", "user.email", "[email protected]"]);+ await run("git", ["-C", root, "config", "user.name", "T"]);+ await mkdir(join(root, "src"));+ await writeFile(join(root, "src", "a.ts"), "export const a = 1;\n");+ await run("git", ["-C", root, "add", "src/a.ts"]);+ await run("git", ["-C", root, "commit", "-q", "-m", "feat: add a"]);+ const short = (await run("git", ["-C", root, "rev-parse", "--short", "HEAD"])).stdout.trim();++ await saveSession(+ "s1",+ session({+ sessionId: "s1",+ title: "one",+ epoch: "e1",+ startedAt: "2026-01-02T00:00:00.000Z",+ nodes: [+ node("h1", "message", "Write a", null, {+ at: "2026-01-02T01:00:00.000Z",+ commits: [short],+ }),+ node("h2", "message", "Note it", "h1", {+ at: "2026-01-02T02:00:00.000Z",+ files: ["notes.md"],+ }),+ ],+ }),+ );++ const model = await buildProject({ dir: root, io, templateHtml: TEMPLATE, quiet: true });++ expect(model.files?.map((file) => [file.path, file.count])).toEqual([+ ["notes.md", 1],+ ["src/a.ts", 1],+ ]);+ expect(model.files?.[1]?.hits[0]).toMatchObject({+ sessionId: "s1",+ messageId: "h1",+ label: "m1",+ commits: [short],+ });+ expect((embedded(await readFile(paths().html, "utf8")) as { files?: unknown }).files).toEqual(+ model.files,+ );+ });+it("embeds the current settings in the map for the file:// modal", async () => {await configSet("messageSummaries", "true", io);const model = await buildProject({ dir: root, io, templateHtml: TEMPLATE, quiet: true });diff --git a/packages/cli/test/files.test.ts b/packages/cli/test/files.test.tsnew file mode 100644index 0000000..6d37989--- /dev/null+++ b/packages/cli/test/files.test.ts@@ -0,0 +1,272 @@+import { execFile } from "node:child_process";+import { mkdir, writeFile } from "node:fs/promises";+import { join } from "node:path";+import { promisify } from "node:util";+import { beforeEach, describe, expect, it } from "vitest";+import { init } from "../src/commands/init.js";+import { logFile } from "../src/commands/log.js";+import { projectFiles } from "../src/git.js";+import { createProgram } from "../src/program.js";+import type { Session } from "../src/schema/session.js";+import { projectPaths } from "../src/store/paths.js";+import { buildFileHistory, type FileSourceSession, modelSessions } from "../src/view/files.js";+import type { ViewNode } from "../src/view/model.js";+import { envFor, type FakeIo, fakeIo, T0, tempDir } from "./helpers.js";++const run = promisify(execFile);++function message(over: Partial<ViewNode> & { id: string; title: string }): ViewNode {+ return { kind: "message", parent: null, ...over };+}++function source(sessionId: string, title: string, messages: ViewNode[]): FileSourceSession {+ return { sessionId, title, messages };+}++describe("buildFileHistory", () => {+ it("unions the message's files with the files of its commits, once per path", () => {+ const files = buildFileHistory(+ [+ source("s1", "Ship it", [+ message({+ id: "h1",+ label: "m1",+ title: "Add a and b",+ at: "2026-10-24T10:00:00.000Z",+ files: ["src/a.ts"],+ commits: ["c1"],+ }),+ ]),+ ],+ new Map([["c1", ["src/a.ts", "src/b.ts"]]]),+ );+ expect(files.map((file) => file.path)).toEqual(["src/a.ts", "src/b.ts"]);+ expect(files[0]?.count).toBe(1);+ expect(files[0]?.hits[0]).toMatchObject({+ sessionId: "s1",+ sessionTitle: "Ship it",+ messageId: "h1",+ label: "m1",+ title: "Add a and b",+ commits: ["c1"],+ });+ });++ it("lists files by last touch and messages newest first", () => {+ const files = buildFileHistory([+ source("s1", "First chat", [+ message({ id: "h1", title: "Older", at: "2026-10-20T09:00:00.000Z", files: ["old.ts"] }),+ message({ id: "h2", title: "Newer", at: "2026-10-24T09:00:00.000Z", files: ["new.ts"] }),+ message({ id: "h3", title: "Back", at: "2026-10-24T11:00:00.000Z", files: ["new.ts"] }),+ ]),+ ]);+ expect(files.map((file) => [file.path, file.count, file.lastAt])).toEqual([+ ["new.ts", 2, "2026-10-24T11:00:00.000Z"],+ ["old.ts", 1, "2026-10-20T09:00:00.000Z"],+ ]);+ expect(files[0]?.hits.map((hit) => hit.messageId)).toEqual(["h3", "h2"]);+ });++ it("files a message under the branch that was running when it was sent", () => {+ const branch = {+ title: "Parser",+ asked: "How?",+ outcome: "Done.",+ open: "",+ };+ const files = buildFileHistory([+ source("s1", "Ship it", [+ message({ id: "h1", title: "Start", files: ["a.ts"], branch }),+ message({ id: "h2", title: "Continue", files: ["b.ts"] }),+ ]),+ ]);+ const a = files.find((file) => file.path === "a.ts");+ const b = files.find((file) => file.path === "b.ts");+ expect(a?.hits[0]?.branch).toBe("Parser");+ expect(b?.hits[0]?.branch).toBe("Parser");+ });++ it("keeps recorded commits git cannot read, and drops ones that missed the file", () => {+ const files = buildFileHistory(+ [+ source("s1", "Ship it", [+ message({+ id: "h1",+ title: "Known and unknown",+ files: ["a.ts"],+ commits: ["c1", "gone"],+ }),+ message({ id: "h2", title: "Two commits", files: ["b.ts"], commits: ["c1", "c2"] }),+ ]),+ ],+ new Map([+ ["c1", ["a.ts"]],+ ["c2", ["c.ts"]],+ ]),+ );+ expect(files.find((file) => file.path === "a.ts")?.hits[0]?.commits).toEqual(["c1", "gone"]);+ expect(files.find((file) => file.path === "b.ts")?.hits[0]?.commits).toEqual([]);+ });++ it("returns nothing for a project with no recorded files", () => {+ expect(buildFileHistory([source("s1", "Empty", [])])).toEqual([]);+ });++ it("flattens a page's epochs and unassigned sessions for the union", () => {+ const sessions = modelSessions({+ kind: "lineage",+ schema: 1,+ project: { name: "p", path: "/p", generatedAt: T0 },+ status: { goal: "", done: [], pending: [], next: "", lastActivity: null },+ epochs: [+ {+ id: "e1",+ title: "One",+ createdAt: T0,+ sessions: [+ {+ sessionId: "s1",+ agent: "claude-code",+ title: "Epoch chat",+ epoch: "e1",+ startedAt: T0,+ updatedAt: T0,+ status: { goal: "", done: [], pending: [], next: "" },+ messages: [],+ transcriptAvailable: true,+ },+ ],+ },+ ],+ unassigned: [+ {+ sessionId: "s2",+ agent: "claude-code",+ title: "Loose chat",+ epoch: null,+ startedAt: T0,+ updatedAt: T0,+ status: { goal: "", done: [], pending: [], next: "" },+ messages: [],+ transcriptAvailable: true,+ },+ ],+ });+ expect(sessions.map((session) => session.sessionId)).toEqual(["s1", "s2"]);+ });+});++describe("projectFiles", () => {+ it("passes a project at the repository root through unchanged", () => {+ const files = new Map([["c1", ["src/a.ts"]]]);+ expect(projectFiles("/repo", "/repo", files)).toEqual(files);+ });++ it("rebases commit paths onto a project below the repository root", () => {+ const out = projectFiles(+ "/repo",+ "/repo/packages/app",+ new Map([+ ["c1", ["packages/app/src/a.ts", "packages/other/b.ts"]],+ ["c2", ["README.md"]],+ ]),+ );+ expect(out.get("c1")).toEqual(["src/a.ts"]);+ // A commit that only touched files outside the project is left out.+ expect(out.has("c2")).toBe(false);+ });+});++describe("codelineage log --file", () => {+ let dir: string;+ let root: string;+ let io: FakeIo;+ let shortA: string;++ const git = async (...args: string[]) => run("git", ["-C", root, ...args]);++ function session(over: Partial<Session> & { sessionId: string }): Session {+ return {+ schema: 1,+ agent: "claude-code",+ title: "",+ epoch: null,+ startedAt: T0,+ updatedAt: T0,+ status: { goal: "", done: [], pending: [], next: "" },+ nodes: [],+ ...over,+ };+ }++ beforeEach(async () => {+ dir = await tempDir();+ root = join(dir, "proj");+ await mkdir(root);+ io = fakeIo(envFor(dir));+ await init(root, { name: "proj", retention: "keep", language: "auto" }, fakeIo(envFor(dir)));+ await git("init", "-q");+ await git("config", "user.email", "[email protected]");+ await git("config", "user.name", "T");+ await writeFile(join(root, "a.txt"), "one\n");+ await git("add", "a.txt");+ await git("commit", "-q", "-m", "feat: add a");+ shortA = (await git("rev-parse", "--short", "HEAD")).stdout.trim();++ const record = session({+ sessionId: "s1",+ title: "Ship the parser",+ nodes: [+ {+ id: "h1",+ parent: null,+ kind: "message",+ title: "Add a.txt",+ at: "2026-10-20T09:00:00.000Z",+ commits: [shortA],+ },+ {+ id: "h2",+ parent: "h1",+ kind: "message",+ title: "Come back to a.txt",+ at: "2026-10-20T10:00:00.000Z",+ files: ["a.txt"],+ },+ ],+ });+ await writeFile(projectPaths(root).session("s1"), JSON.stringify(record));+ });++ it("lists the messages that touched the file, newest first", async () => {+ const file = await logFile({ dir: root, file: "a.txt", io });+ expect(file?.count).toBe(2);+ expect(io.lines[0]).toBe("a.txt 2 messages (newest first)");+ expect(io.lines[1]).toContain("h2");+ expect(io.lines[1]).toContain("m2");+ expect(io.lines[1]).toContain("Come back to a.txt");+ expect(io.lines[1]).toContain("Ship the parser");+ expect(io.lines[2]).toContain(`[${shortA.slice(0, 7)}]`);+ expect(io.lines[2]).toContain("Add a.txt");+ });++ it("normalizes a leading ./ and prints JSON on request", async () => {+ await logFile({ dir: root, file: "./a.txt", io, json: true });+ const parsed = JSON.parse(io.lines.join("\n")) as { path: string; count: number };+ expect(parsed.path).toBe("a.txt");+ expect(parsed.count).toBe(2);+ });++ it("says plainly when no record touched the file", async () => {+ const file = await logFile({ dir: root, file: "b.txt", io });+ expect(file).toBeNull();+ expect(io.lines).toEqual(["No recorded message touched b.txt."]);+ });++ it("runs through the CLI", async () => {+ const program = createProgram(() => io);+ await program.parseAsync(["log", "--file", "a.txt", "-C", root], { from: "user" });+ expect(io.lines[0]).toContain("a.txt");+ expect(io.lines[1]).toContain("Come back to a.txt");+ });+});diff --git a/packages/template/src/FilesView.tsx b/packages/template/src/FilesView.tsxnew file mode 100644index 0000000..fc70618--- /dev/null+++ b/packages/template/src/FilesView.tsx@@ -0,0 +1,132 @@+import { useEffect, useState } from "react";+import type { ViewFile } from "../../cli/src/view/model.js";+import { formatStamp } from "./format.js";+import { shortHash } from "./graph.js";++/**+ * The files view (Story 8.15): every file a recorded message touched, most+ * recently touched first. Opening a file lists the messages that changed it;+ * clicking one opens that message in place on the graph, the same drill-down a+ * dot click gives.+ */++export interface FilesTarget {+ sessionId: string;+ messageId: string;+}++export function FilesView({+ files,+ active,+ onSelect,+ onClose,+}: {+ files: readonly ViewFile[] | undefined;+ /** The message the map has selected, if any. */+ active: FilesTarget | null;+ onSelect: (target: FilesTarget) => void;+ onClose: () => void;+}) {+ const all = files ?? [];+ const [openPath, setOpenPath] = useState<string | null>(null);++ // A map click (or a search hit) may land on a message whose file is not open;+ // reveal the file that holds it so the row and its history are visible.+ const activePath =+ active === null+ ? null+ : (all.find((file) =>+ file.hits.some(+ (hit) => hit.sessionId === active.sessionId && hit.messageId === active.messageId,+ ),+ )?.path ?? null);+ useEffect(() => {+ if (activePath !== null) setOpenPath(activePath);+ }, [activePath]);++ return (+ <nav className="outline files-view" aria-label="File history">+ <header className="outline-head">+ <span className="outline-title">Files</span>+ <span className="outline-badge">{all.length}</span>+ <button type="button" className="drilldown-close" aria-label="Hide files" onClick={onClose}>+ ×+ </button>+ </header>+ <div className="outline-scroll">+ {all.length === 0 ? (+ <p className="empty">+ No files recorded yet. The agent lists the files each message touched.+ </p>+ ) : (+ <ul className="outline-list">+ {all.map((file) => {+ const open = openPath === file.path;+ return (+ <li key={file.path}>+ <div className="outline-row">+ <button+ type="button"+ className="outline-toggle"+ aria-expanded={open}+ aria-label={open ? "Collapse" : "Expand"}+ onClick={() => setOpenPath(open ? null : file.path)}+ >+ {open ? "▾" : "▸"}+ </button>+ <button+ type="button"+ className={`outline-item file-row${activePath === file.path ? " is-active" : ""}`}+ title={file.path}+ onClick={() => setOpenPath(open ? null : file.path)}+ >+ <span className="label file-path">{file.path}</span>+ <span className="outline-count">{file.count}</span>+ </button>+ </div>+ {open ? (+ <ul className="file-hits">+ {file.hits.map((hit) => {+ const selected =+ active?.sessionId === hit.sessionId && active.messageId === hit.messageId;+ return (+ <li key={`${hit.sessionId}:${hit.messageId}`}>+ <button+ type="button"+ className={`file-hit${selected ? " is-active" : ""}`}+ onClick={() =>+ onSelect({ sessionId: hit.sessionId, messageId: hit.messageId })+ }+ >+ <span className="file-hit-line">+ <span className="file-hit-time">{formatStamp(hit.at ?? null)}</span>+ <span className="file-hash">{shortHash(hit.messageId)}</span>+ <span className="file-label">{hit.label}</span>+ <span className="file-hit-title">{hit.title}</span>+ </span>+ <span className="file-hit-meta">+ <span className="file-hit-session">{hit.sessionTitle}</span>+ {hit.branch === undefined ? null : (+ <span className="file-hit-branch">╭ {hit.branch}</span>+ )}+ {hit.commits.length === 0 ? null : (+ <span className="file-hit-commit">+ {hit.commits.map((hash) => hash.slice(0, 7)).join(" ")}+ </span>+ )}+ </span>+ </button>+ </li>+ );+ })}+ </ul>+ ) : null}+ </li>+ );+ })}+ </ul>+ )}+ </div>+ </nav>+ );+}diff --git a/packages/template/src/Graph.tsx b/packages/template/src/Graph.tsxindex 0991b8b..c3cb208 100644--- a/packages/template/src/Graph.tsx+++ b/packages/template/src/Graph.tsx@@ -13,6 +13,7 @@ import "@xyflow/react/dist/style.css";import { createContext, useCallback, useContext, useEffect, useMemo, useState } from "react";import type { LineageViewModel, ViewSession } from "../../cli/src/view/model.js";import { hitMessageIds, hitSessionIds } from "../../cli/src/view/search.js";+import { type FilesTarget, FilesView } from "./FilesView.js";import { useFullscreen } from "./fullscreen.js";import { GitGraph } from "./GitGraph.js";import { type GitLayout, layoutGitGraph } from "./gitLayout.js";@@ -212,6 +213,8 @@ function Flow({ model, search }: { model: LineageViewModel; search: MapSearchStaconst [unfolded, setUnfolded] = useState<Set<string>>(() => new Set());const [openAll, setOpenAll] = useState(false);const [showOutline, setShowOutline] = useState(true);+ // The files view and the outline share the left column, so only one shows.+ const [showFiles, setShowFiles] = useState(false);const { expanded: fullscreen, toggle: toggleFullscreen } = useFullscreen();const [focusedId, setFocusedId] = useState<string | null>(() => {if (initial === null) return null;@@ -463,6 +466,27 @@ function Flow({ model, search }: { model: LineageViewModel; search: MapSearchSta[ensureOpen],);+ // A file row (8.15) opens its message exactly like a dot click, and the view+ // moves to it once the session's layout is in place.+ const [fileJumps, setFileJumps] = useState(0);+ const selectFromFiles = useCallback(+ (target: FilesTarget) => {+ openNode(target.sessionId, target.messageId);+ setFileJumps((value) => value + 1);+ },+ [openNode],+ );+ const filePoint = useMemo(+ () => (target === null ? null : pointOf(target.sessionId, target.nodeId)),+ // `pointOf` changes when an opened session's layout changes, which is how a+ // click that opens a session resolves its point on the next render.+ [target?.sessionId, target?.nodeId, pointOf],+ );+ const fileJump = useMemo(+ () => (fileJumps === 0 || filePoint === null ? null : { key: fileJumps, point: filePoint }),+ [fileJumps, filePoint],+ );+const actions = useMemo(() => ({ selection, openIds, openSession: toggleSession, openNode, openContinue, unfold }),[selection, openIds, toggleSession, openNode, openContinue, unfold],@@ -551,13 +575,39 @@ function Flow({ model, search }: { model: LineageViewModel; search: MapSearchStatype="button"className="outline-button"aria-pressed={showOutline}- onClick={() => setShowOutline((value) => !value)}+ onClick={() => {+ setShowOutline((value) => !value);+ setShowFiles(false);+ }}>{showOutline ? "Hide outline" : "Show outline"}</button>+ <button+ type="button"+ className="outline-button"+ aria-pressed={showFiles}+ title="Which conversations touched which file"+ onClick={() => {+ setShowFiles((value) => !value);+ setShowOutline(false);+ }}+ >+ {showFiles ? "Hide files" : "Files"}+ </button></div><div className="graph-wrap">- {showOutline ? (+ {showFiles ? (+ <FilesView+ files={model.files}+ active={+ selection?.type === "node"+ ? { sessionId: selection.sessionId, messageId: selection.nodeId }+ : null+ }+ onSelect={selectFromFiles}+ onClose={() => setShowFiles(false)}+ />+ ) : showOutline ? (<Outlinemodel={model}activeId={focusedId}@@ -574,6 +624,7 @@ function Flow({ model, search }: { model: LineageViewModel; search: MapSearchStafocusRow={focusRow}jump={jump}searchJump={searchJump}+ fileJump={fileJump}fit={fits}/>)}@@ -600,6 +651,7 @@ function MapCanvas({focusRow,jump,searchJump,+ fileJump,fit,}: {nodes: MapFlowNode[];@@ -609,6 +661,8 @@ function MapCanvas({jump: { key: number; point: { x: number; y: number } | null } | null;/** A search move: the active hit or a pasted hash (Story 8.14). */searchJump: { key: number; point: { x: number; y: number } } | null;+ /** A files-view click: the message it opened (Story 8.15). */+ fileJump: { key: number; point: { x: number; y: number } } | null;/** A new value frames the whole map again (after "Fold all"). */fit: number;}) {@@ -656,6 +710,13 @@ function MapCanvas({centre(searchPoint);}, [searchKey, searchPoint]);+ const fileKey = fileJump?.key ?? 0;+ const filePoint = fileJump?.point ?? null;+ useEffect(() => {+ if (fileKey === 0 || filePoint === null) return;+ centre(filePoint);+ }, [fileKey, filePoint]);+useEffect(() => {const timer = window.setTimeout(() => {const canvas = document.querySelector(".react-flow")?.getBoundingClientRect();diff --git a/packages/template/src/fixture.ts b/packages/template/src/fixture.tsindex e7e66ca..c18ce44 100644--- a/packages/template/src/fixture.ts+++ b/packages/template/src/fixture.ts@@ -86,6 +86,7 @@ export const fixture: LineageViewModel = {message("m2", "Wire the data contract", "m1", "2026-10-24T09:12:00.000Z", {summary: "The page reads the JSON script element and types it once.",work: ["Added view/model.ts shared by CLI and template"],+ files: ["packages/cli/src/view/model.ts", "packages/cli/src/view/lineage.ts"],}),message("m3", "Read data from the DOM", "m2", "2026-10-24T09:20:00.000Z", {summary: "A fetch would break file://; the JSON element survives inlining.",@@ -99,12 +100,14 @@ export const fixture: LineageViewModel = {{ hash: "1a2b3c4", subject: "feat(template): add the dev fixture" },{ hash: "9f8e7d6" },],+ files: ["packages/template/src/fixture.ts"],}),message("m5", "Check the page in the browser", "m4", "2026-10-24T10:02:00.000Z", {summary: "Layout measured; console clean.",}),message("m6", "Draw nested groups", "m4", "2026-10-24T10:20:00.000Z", {summary: "A second branch off the fixture work.",+ files: ["packages/template/src/Graph.tsx"],branch: {title: "Nested groups",asked: "How do epochs, sessions and messages nest?",@@ -121,6 +124,7 @@ export const fixture: LineageViewModel = {}),message("m9", "Lineage graph idea", null, "2026-10-24T11:42:00.000Z", {summary: "A git graph of the user's messages.",+ files: ["packages/cli/src/view/files.ts"],branch: {title: "Git graph",asked: "What if the map read like a git history?",@@ -152,6 +156,7 @@ export const fixture: LineageViewModel = {[message("c1", "Harden session writes", null, "2026-10-20T09:00:00.000Z", {summary: "Locked read → merge → write with redaction.",+ files: ["packages/cli/src/store/stores.ts"],branch: {title: "Safe writes",asked: "How do two turns write the same session?",@@ -199,6 +204,111 @@ export const fixture: LineageViewModel = {},),],+ // Story 8.15: the files view, as `build` unions message files and commit files.+ files: [+ {+ path: "packages/cli/src/view/files.ts",+ count: 1,+ lastAt: "2026-10-24T11:42:00.000Z",+ hits: [+ {+ sessionId: "fixture-template",+ sessionTitle: "Template package and single-file output",+ messageId: "m9",+ label: "m9",+ at: "2026-10-24T11:42:00.000Z",+ title: "Lineage graph idea",+ branch: "Git graph",+ commits: [],+ },+ ],+ },+ {+ path: "packages/template/src/Graph.tsx",+ count: 1,+ lastAt: "2026-10-24T10:20:00.000Z",+ hits: [+ {+ sessionId: "fixture-template",+ sessionTitle: "Template package and single-file output",+ messageId: "m6",+ label: "m6",+ at: "2026-10-24T10:20:00.000Z",+ title: "Draw nested groups",+ branch: "Nested groups",+ commits: [],+ },+ ],+ },+ {+ path: "packages/template/src/fixture.ts",+ count: 1,+ lastAt: "2026-10-24T09:41:00.000Z",+ hits: [+ {+ sessionId: "fixture-template",+ sessionTitle: "Template package and single-file output",+ messageId: "m4",+ label: "m4",+ at: "2026-10-24T09:41:00.000Z",+ title: "Build the dev fixture",+ branch: "Template scaffold",+ commits: ["1a2b3c4", "9f8e7d6"],+ },+ ],+ },+ {+ path: "packages/cli/src/view/model.ts",+ count: 1,+ lastAt: "2026-10-24T09:12:00.000Z",+ hits: [+ {+ sessionId: "fixture-template",+ sessionTitle: "Template package and single-file output",+ messageId: "m2",+ label: "m2",+ at: "2026-10-24T09:12:00.000Z",+ title: "Wire the data contract",+ branch: "Template scaffold",+ commits: [],+ },+ ],+ },+ {+ path: "packages/cli/src/view/lineage.ts",+ count: 1,+ lastAt: "2026-10-24T09:12:00.000Z",+ hits: [+ {+ sessionId: "fixture-template",+ sessionTitle: "Template package and single-file output",+ messageId: "m2",+ label: "m2",+ at: "2026-10-24T09:12:00.000Z",+ title: "Wire the data contract",+ branch: "Template scaffold",+ commits: [],+ },+ ],+ },+ {+ path: "packages/cli/src/store/stores.ts",+ count: 1,+ lastAt: "2026-10-20T09:00:00.000Z",+ hits: [+ {+ sessionId: "fixture-capture",+ sessionTitle: "Session merge and redaction",+ messageId: "c1",+ label: "c1",+ at: "2026-10-20T09:00:00.000Z",+ title: "Harden session writes",+ branch: "Safe writes",+ commits: [],+ },+ ],+ },+ ],// Story 8.12: the switcher's data, as `build` collects it from the registry.switcher: [{diff --git a/packages/template/src/styles.css b/packages/template/src/styles.cssindex 165878e..729eb4c 100644--- a/packages/template/src/styles.css+++ b/packages/template/src/styles.css@@ -700,6 +700,90 @@ body:has(.map-shell.is-expanded) {font-size: 11px;}+/* Files view (Story 8.15): the conversations that changed a file. */+.files-view {+ width: 330px;+}++.file-row .file-path {+ font-family: var(--mono, ui-monospace, SFMono-Regular, Menlo, monospace);+ font-size: 12px;+}++.file-hits {+ margin: 0 0 4px;+ padding: 0 0 0 20px;+ list-style: none;+}++.file-hit {+ display: flex;+ flex-direction: column;+ gap: 2px;+ width: 100%;+ padding: 5px 8px;+ color: var(--text);+ background: transparent;+ border: 0;+ border-radius: 5px;+ font: inherit;+ font-size: 12px;+ text-align: left;+ cursor: pointer;+}++.file-hit:hover {+ background: #1d222c;+}++.file-hit.is-active {+ background: #243040;+ outline: 1px solid var(--accent);+}++.file-hit-line {+ display: flex;+ align-items: baseline;+ gap: 6px;+ min-width: 0;+}++.file-hit-time {+ flex: none;+ color: var(--muted);+ font-size: 11px;+ font-variant-numeric: tabular-nums;+}++.file-hash,+.file-label {+ flex: none;+ color: var(--muted);+ font-family: var(--mono, ui-monospace, SFMono-Regular, Menlo, monospace);+ font-size: 11px;+}++.file-hit-title {+ overflow: hidden;+ white-space: nowrap;+ text-overflow: ellipsis;+}++.file-hit-meta {+ display: flex;+ gap: 6px;+ overflow: hidden;+ color: var(--muted);+ font-size: 11px;+ white-space: nowrap;+ text-overflow: ellipsis;+}++.file-hit-branch,+.file-hit-commit {+ font-family: var(--mono, ui-monospace, SFMono-Regular, Menlo, monospace);+}+/* The map draws its own git graph; React Flow only pans, zooms and frames it. */.map-node .git-graph {margin: 0;