@arcreflex/agent-transcripts 0.1.4 → 0.1.8

package/src/utils/provenance.ts

@@ -0,0 +1,228 @@
+/**
+ * Provenance tracking utilities.
+ *
+ * Tracks the relationship between source files and output transcripts
+ * via transcripts.json index (primary) and YAML front matter (for self-documenting files).
+ */
+
+import { join, resolve } from "path";
+import { existsSync } from "fs";
+import { rename, unlink } from "fs/promises";
+
+const INDEX_FILENAME = "transcripts.json";
+
+// ============================================================================
+// Index Types
+// ============================================================================
+
+export interface TranscriptEntry {
+  source: string; // absolute path to source
+  sourceMtime: number; // ms since epoch
+  sessionId: string; // full session ID from source filename
+  segmentIndex?: number; // for multi-transcript sources (1-indexed)
+  syncedAt: string; // ISO timestamp
+}
+
+export interface TranscriptsIndex {
+  version: 1;
+  entries: Record<string, TranscriptEntry>; // outputFilename → entry
+}
+
+// ============================================================================
+// Path Utilities
+// ============================================================================
+
+/**
+ * Normalize a source path to absolute for consistent index keys.
+ */
+export function normalizeSourcePath(sourcePath: string): string {
+  if (sourcePath === "<stdin>") return sourcePath;
+  return resolve(sourcePath);
+}
+
+// ============================================================================
+// Index I/O
+// ============================================================================
+
+/**
+ * Load transcripts.json index from output directory.
+ * Returns empty index if file doesn't exist. Warns on corrupt file.
+ */
+export async function loadIndex(outputDir: string): Promise<TranscriptsIndex> {
+  const indexPath = join(outputDir, INDEX_FILENAME);
+  try {
+    const content = await Bun.file(indexPath).text();
+    const data = JSON.parse(content) as TranscriptsIndex;
+    // Validate version
+    if (data.version !== 1) {
+      console.error(
+        `Warning: Unknown index version ${data.version}, creating fresh index`,
+      );
+      return { version: 1, entries: {} };
+    }
+    return data;
+  } catch (err) {
+    // Distinguish between missing file (expected) and corrupt file (unexpected)
+    const isEnoent =
+      err instanceof Error && (err as NodeJS.ErrnoException).code === "ENOENT";
+    if (!isEnoent) {
+      console.error(
+        `Warning: Could not parse index file, starting fresh: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    return { version: 1, entries: {} };
+  }
+}
+
+/**
+ * Save transcripts.json index to output directory.
+ * Uses atomic write (write to .tmp, then rename) to prevent corruption.
+ */
+export async function saveIndex(
+  outputDir: string,
+  index: TranscriptsIndex,
+): Promise<void> {
+  const indexPath = join(outputDir, INDEX_FILENAME);
+  const tmpPath = `${indexPath}.tmp`;
+
+  const content = JSON.stringify(index, null, 2) + "\n";
+  await Bun.write(tmpPath, content);
+  try {
+    await rename(tmpPath, indexPath);
+  } catch (err) {
+    // Clean up temp file on failure
+    try {
+      await unlink(tmpPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+    throw err;
+  }
+}
+
+// ============================================================================
+// Index Operations
+// ============================================================================
+
+/**
+ * Get all output filenames for a given source path.
+ */
+export function getOutputsForSource(
+  index: TranscriptsIndex,
+  sourcePath: string,
+): string[] {
+  const outputs: string[] = [];
+  for (const [filename, entry] of Object.entries(index.entries)) {
+    if (entry.source === sourcePath) {
+      outputs.push(filename);
+    }
+  }
+  return outputs;
+}
+
+/**
+ * Check if outputs for a source are stale.
+ * Returns true if:
+ * - No outputs exist for this source
+ * - Output count doesn't match expected
+ * - Any output file is missing from disk
+ * - Source mtime is newer than recorded mtime
+ */
+export function isStale(
+  index: TranscriptsIndex,
+  sourcePath: string,
+  sourceMtime: number,
+  expectedCount: number,
+  outputDir: string,
+): boolean {
+  const outputs = getOutputsForSource(index, sourcePath);
+
+  if (outputs.length !== expectedCount) {
+    return true;
+  }
+
+  // Check if outputs actually exist on disk
+  for (const filename of outputs) {
+    if (!existsSync(join(outputDir, filename))) {
+      return true;
+    }
+  }
+
+  // Check if source has been modified since last sync
+  for (const filename of outputs) {
+    const entry = index.entries[filename];
+    if (entry && entry.sourceMtime < sourceMtime) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Set or update an entry in the index.
+ * outputPath should be relative to the output directory.
+ */
+export function setEntry(
+  index: TranscriptsIndex,
+  outputPath: string,
+  entry: TranscriptEntry,
+): void {
+  index.entries[outputPath] = entry;
+}
+
+/**
+ * Remove all entries for a given source path.
+ * Returns the removed entries (for potential restoration on error).
+ */
+export function removeEntriesForSource(
+  index: TranscriptsIndex,
+  sourcePath: string,
+): Array<{ filename: string; entry: TranscriptEntry }> {
+  const removed: Array<{ filename: string; entry: TranscriptEntry }> = [];
+  for (const [filename, entry] of Object.entries(index.entries)) {
+    if (entry.source === sourcePath) {
+      removed.push({ filename, entry });
+      delete index.entries[filename];
+    }
+  }
+  return removed;
+}
+
+/**
+ * Restore previously removed entries to the index.
+ */
+export function restoreEntries(
+  index: TranscriptsIndex,
+  entries: Array<{ filename: string; entry: TranscriptEntry }>,
+): void {
+  for (const { filename, entry } of entries) {
+    index.entries[filename] = entry;
+  }
+}
+
+// ============================================================================
+// File Operations
+// ============================================================================
+
+/**
+ * Delete output files, with warnings on failure.
+ */
+export async function deleteOutputFiles(
+  outputDir: string,
+  filenames: string[],
+  quiet = false,
+): Promise<void> {
+  for (const filename of filenames) {
+    const fullPath = join(outputDir, filename);
+    try {
+      await unlink(fullPath);
+      if (!quiet) {
+        console.error(`Deleted: ${fullPath}`);
+      }
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`Warning: could not delete ${fullPath}: ${msg}`);
+    }
+  }
+}

package/test/snapshots.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it } from "bun:test";
 import { join, dirname } from "path";
 import { Glob } from "bun";
+import { getAdapter } from "../src/adapters/index.ts";
+import { renderTranscript } from "../src/render.ts";
 
 const fixturesDir = join(dirname(import.meta.path), "fixtures/claude");
 const binPath = join(dirname(import.meta.path), "../bin/agent-transcripts");
@@ -25,43 +27,47 @@ describe("snapshot tests", () => {
 
       const expectedOutput = await Bun.file(expectedPath).text();
 
-      // Run the CLI: parse to temp JSON, then render to temp MD
-      const tempJson = `/tmp/test-${name}-${Date.now()}.json`;
-      const tempMd = `/tmp/test-${name}-${Date.now()}.md`;
+      // Direct function call: parse with adapter, then render
+      const adapter = getAdapter("claude-code")!;
+      const content = await Bun.file(relativeInputPath).text();
+      const transcripts = adapter.parse(content, relativeInputPath);
 
-      // Parse
-      const parseResult = Bun.spawnSync([
-        binPath,
-        "parse",
-        relativeInputPath,
-        "--adapter",
-        "claude-code",
-        "-o",
-        tempJson,
-      ]);
-      expect(parseResult.exitCode).toBe(0);
+      expect(transcripts.length).toBeGreaterThan(0);
 
-      // Render
-      const renderResult = Bun.spawnSync([
-        binPath,
-        "render",
-        tempJson,
-        "-o",
-        tempMd,
-      ]);
-      expect(renderResult.exitCode).toBe(0);
+      // Render the first transcript (our fixtures are single-transcript)
+      const actualOutput = renderTranscript(transcripts[0]);
 
-      // Compare output
-      const actualOutput = await Bun.file(tempMd).text();
       expect(actualOutput.trimEnd()).toBe(expectedOutput.trimEnd());
-
-      // Cleanup
-      await Bun.file(tempJson)
-        .delete()
-        .catch(() => {});
-      await Bun.file(tempMd)
-        .delete()
-        .catch(() => {});
     });
   }
 });
+
+describe("CLI integration", () => {
+  it("convert to stdout works", async () => {
+    const inputFile = inputFiles[0];
+    if (!inputFile) {
+      throw new Error("No input fixtures found");
+    }
+
+    const relativeInputPath = `test/fixtures/claude/${inputFile}`;
+    const expectedPath = join(
+      fixturesDir,
+      inputFile.replace(".input.jsonl", ".output.md"),
+    );
+    const expectedOutput = await Bun.file(expectedPath).text();
+
+    // Run CLI: convert with stdout output
+    const result = Bun.spawnSync([
+      binPath,
+      "convert",
+      relativeInputPath,
+      "--adapter",
+      "claude-code",
+    ]);
+
+    expect(result.exitCode).toBe(0);
+
+    const actualOutput = result.stdout.toString();
+    expect(actualOutput.trimEnd()).toBe(expectedOutput.trimEnd());
+  });
+});