@vellumai/assistant 0.8.3 → 0.8.4

package/src/documents/document-comments-store.test.ts

@@ -0,0 +1,338 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { makeMockLogger } from "../__tests__/helpers/mock-logger.js";
+
+mock.module("../util/logger.js", () => ({
+  getLogger: () => makeMockLogger(),
+}));
+
+import { initializeDb } from "../memory/db-init.js";
+import { rawRun, resetTestTables } from "../memory/raw-query.js";
+import {
+  createComment,
+  deleteComment,
+  getComment,
+  getCommentCountForDocument,
+  listComments,
+  reopenComment,
+  resolveComment,
+} from "./document-comments-store.js";
+
+initializeDb();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const SURFACE_ID = "doc-test-surface";
+const CONVERSATION_ID = "conv-test-123";
+
+/** Insert a minimal document so FK constraints are satisfied. */
+function seedDocument(surfaceId: string = SURFACE_ID): void {
+  const now = Date.now();
+  rawRun(
+    /*sql*/ `INSERT OR IGNORE INTO conversations (id, created_at, updated_at) VALUES (?, ?, ?)`,
+    CONVERSATION_ID,
+    now,
+    now,
+  );
+  rawRun(
+    /*sql*/ `INSERT OR IGNORE INTO documents (surface_id, conversation_id, title, content, word_count, created_at, updated_at)
+     VALUES (?, ?, 'Test Doc', 'body', 2, ?, ?)`,
+    surfaceId,
+    CONVERSATION_ID,
+    now,
+    now,
+  );
+}
+
+beforeEach(() => {
+  resetTestTables("document_comments", "documents", "conversations");
+  seedDocument();
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("createComment", () => {
+  test("creates a comment and returns the record", () => {
+    const comment = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Looks good!",
+    });
+
+    expect(comment.id).toMatch(/^comment-/);
+    expect(comment.surfaceId).toBe(SURFACE_ID);
+    expect(comment.conversationId).toBe(CONVERSATION_ID);
+    expect(comment.author).toBe("user1");
+    expect(comment.content).toBe("Looks good!");
+    expect(comment.status).toBe("open");
+    expect(comment.parentCommentId).toBeNull();
+    expect(comment.anchorStart).toBeNull();
+    expect(comment.resolvedBy).toBeNull();
+    expect(comment.resolvedAt).toBeNull();
+  });
+
+  test("creates a comment with anchor data", () => {
+    const comment = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Fix this typo",
+      anchorStart: 10,
+      anchorEnd: 15,
+      anchorText: "wrold",
+    });
+
+    expect(comment.anchorStart).toBe(10);
+    expect(comment.anchorEnd).toBe(15);
+    expect(comment.anchorText).toBe("wrold");
+  });
+});
+
+describe("getComment", () => {
+  test("returns a comment by id", () => {
+    const created = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Hello",
+    });
+
+    const fetched = getComment(created.id);
+    expect(fetched).not.toBeNull();
+    expect(fetched!.id).toBe(created.id);
+    expect(fetched!.content).toBe("Hello");
+  });
+
+  test("returns null for non-existent id", () => {
+    expect(getComment("comment-nonexistent")).toBeNull();
+  });
+});
+
+describe("listComments", () => {
+  test("lists all comments for a surface ordered by created_at ASC", () => {
+    createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "First",
+    });
+    createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Second",
+    });
+
+    const comments = listComments(SURFACE_ID);
+    expect(comments).toHaveLength(2);
+    expect(comments[0].content).toBe("First");
+    expect(comments[1].content).toBe("Second");
+  });
+
+  test("filters by status=open", () => {
+    const c = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Open one",
+    });
+    createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Resolved one",
+    });
+    resolveComment(c.id, "user1");
+
+    const open = listComments(SURFACE_ID, { status: "open" });
+    expect(open).toHaveLength(1);
+    expect(open[0].content).toBe("Resolved one");
+
+    const resolved = listComments(SURFACE_ID, { status: "resolved" });
+    expect(resolved).toHaveLength(1);
+    expect(resolved[0].content).toBe("Open one");
+  });
+
+  test("filters topLevelOnly (excludes replies)", () => {
+    const parent = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Top-level",
+    });
+    createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Reply",
+      parentCommentId: parent.id,
+    });
+
+    const topLevel = listComments(SURFACE_ID, { topLevelOnly: true });
+    expect(topLevel).toHaveLength(1);
+    expect(topLevel[0].content).toBe("Top-level");
+
+    const all = listComments(SURFACE_ID);
+    expect(all).toHaveLength(2);
+  });
+
+  test("returns empty array for unknown surface", () => {
+    expect(listComments("nonexistent-surface")).toHaveLength(0);
+  });
+});
+
+describe("resolveComment", () => {
+  test("sets resolved fields", () => {
+    const c = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Fix this",
+    });
+
+    const result = resolveComment(c.id, "user1");
+    expect(result).toBe(true);
+
+    const fetched = getComment(c.id);
+    expect(fetched!.status).toBe("resolved");
+    expect(fetched!.resolvedBy).toBe("user1");
+    expect(fetched!.resolvedAt).toBeGreaterThan(0);
+    expect(fetched!.updatedAt).toBeGreaterThanOrEqual(c.updatedAt);
+  });
+
+  test("returns false for non-existent comment", () => {
+    expect(resolveComment("comment-nonexistent", "user1")).toBe(false);
+  });
+});
+
+describe("reopenComment", () => {
+  test("clears resolved fields", () => {
+    const c = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Fix this",
+    });
+    resolveComment(c.id, "user1");
+
+    const result = reopenComment(c.id);
+    expect(result).toBe(true);
+
+    const fetched = getComment(c.id);
+    expect(fetched!.status).toBe("open");
+    expect(fetched!.resolvedBy).toBeNull();
+    expect(fetched!.resolvedAt).toBeNull();
+  });
+
+  test("returns false for non-existent comment", () => {
+    expect(reopenComment("comment-nonexistent")).toBe(false);
+  });
+});
+
+describe("deleteComment", () => {
+  test("deletes a comment", () => {
+    const c = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Delete me",
+    });
+
+    expect(deleteComment(c.id)).toBe(true);
+    expect(getComment(c.id)).toBeNull();
+  });
+
+  test("returns false for non-existent comment", () => {
+    expect(deleteComment("comment-nonexistent")).toBe(false);
+  });
+
+  test("cascades to child replies", () => {
+    const parent = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Parent",
+    });
+    const reply = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Reply",
+      parentCommentId: parent.id,
+    });
+
+    expect(deleteComment(parent.id)).toBe(true);
+    expect(getComment(parent.id)).toBeNull();
+    expect(getComment(reply.id)).toBeNull();
+  });
+});
+
+describe("getCommentCountForDocument", () => {
+  test("counts only open comments", () => {
+    const c = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Open",
+    });
+    createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Also open",
+    });
+
+    expect(getCommentCountForDocument(SURFACE_ID)).toBe(2);
+
+    resolveComment(c.id, "user1");
+    expect(getCommentCountForDocument(SURFACE_ID)).toBe(1);
+  });
+
+  test("returns 0 for surface with no comments", () => {
+    expect(getCommentCountForDocument(SURFACE_ID)).toBe(0);
+  });
+});
+
+describe("thread support", () => {
+  test("reply has parent_comment_id set", () => {
+    const parent = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Parent",
+    });
+    const reply = createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Reply",
+      parentCommentId: parent.id,
+    });
+
+    const fetched = getComment(reply.id);
+    expect(fetched!.parentCommentId).toBe(parent.id);
+  });
+});
+
+describe("cascade on document delete", () => {
+  test("deleting a document removes its comments", () => {
+    createComment({
+      surfaceId: SURFACE_ID,
+      conversationId: CONVERSATION_ID,
+      author: "user1",
+      content: "Will be cascaded",
+    });
+
+    expect(listComments(SURFACE_ID)).toHaveLength(1);
+
+    // Delete the document — FK cascade should remove comments.
+    rawRun(/*sql*/ `DELETE FROM documents WHERE surface_id = ?`, SURFACE_ID);
+
+    expect(listComments(SURFACE_ID)).toHaveLength(0);
+  });
+});

package/src/documents/document-comments-store.ts

@@ -0,0 +1,237 @@
+/**
+ * CRUD operations for document comments.
+ *
+ * Follows the same raw-query pattern as document-store.ts — all SQL uses
+ * snake_case columns, mapped to camelCase TypeScript interfaces via
+ * `mapRowToComment()`.
+ */
+import { randomUUID } from "node:crypto";
+
+import { rawAll, rawGet, rawRun } from "../memory/raw-query.js";
+import { getLogger } from "../util/logger.js";
+
+const log = getLogger("document-comments-store");
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** A comment record with camelCase fields mapped from snake_case DB columns. */
+export interface CommentRecord {
+  id: string;
+  surfaceId: string;
+  conversationId: string;
+  author: string;
+  content: string;
+  anchorStart: number | null;
+  anchorEnd: number | null;
+  anchorText: string | null;
+  parentCommentId: string | null;
+  status: "open" | "resolved";
+  resolvedBy: string | null;
+  resolvedAt: number | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+interface CommentRow {
+  id: string;
+  surface_id: string;
+  conversation_id: string;
+  author: string;
+  content: string;
+  anchor_start: number | null;
+  anchor_end: number | null;
+  anchor_text: string | null;
+  parent_comment_id: string | null;
+  status: string;
+  resolved_by: string | null;
+  resolved_at: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function mapRowToComment(row: CommentRow): CommentRecord {
+  return {
+    id: row.id,
+    surfaceId: row.surface_id,
+    conversationId: row.conversation_id,
+    author: row.author,
+    content: row.content,
+    anchorStart: row.anchor_start,
+    anchorEnd: row.anchor_end,
+    anchorText: row.anchor_text,
+    parentCommentId: row.parent_comment_id,
+    status: row.status as CommentRecord["status"],
+    resolvedBy: row.resolved_by,
+    resolvedAt: row.resolved_at,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// CRUD
+// ---------------------------------------------------------------------------
+
+export function createComment(params: {
+  surfaceId: string;
+  conversationId: string;
+  author: string;
+  content: string;
+  anchorStart?: number | null;
+  anchorEnd?: number | null;
+  anchorText?: string | null;
+  parentCommentId?: string | null;
+}): CommentRecord {
+  const id = `comment-${randomUUID()}`;
+  const now = Date.now();
+
+  rawRun(
+    /*sql*/ `INSERT INTO document_comments
+      (id, surface_id, conversation_id, author, content,
+       anchor_start, anchor_end, anchor_text, parent_comment_id,
+       status, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'open', ?, ?)`,
+    id,
+    params.surfaceId,
+    params.conversationId,
+    params.author,
+    params.content,
+    params.anchorStart ?? null,
+    params.anchorEnd ?? null,
+    params.anchorText ?? null,
+    params.parentCommentId ?? null,
+    now,
+    now,
+  );
+
+  log.info({ id, surfaceId: params.surfaceId }, "Created comment");
+
+  return {
+    id,
+    surfaceId: params.surfaceId,
+    conversationId: params.conversationId,
+    author: params.author,
+    content: params.content,
+    anchorStart: params.anchorStart ?? null,
+    anchorEnd: params.anchorEnd ?? null,
+    anchorText: params.anchorText ?? null,
+    parentCommentId: params.parentCommentId ?? null,
+    status: "open",
+    resolvedBy: null,
+    resolvedAt: null,
+    createdAt: now,
+    updatedAt: now,
+  };
+}
+
+export function getComment(id: string): CommentRecord | null {
+  const row = rawGet<CommentRow>(
+    /*sql*/ `SELECT * FROM document_comments WHERE id = ?`,
+    id,
+  );
+  return row ? mapRowToComment(row) : null;
+}
+
+export function listComments(
+  surfaceId: string,
+  opts?: {
+    status?: "open" | "resolved" | "all";
+    topLevelOnly?: boolean;
+  },
+): CommentRecord[] {
+  const status = opts?.status ?? "all";
+  const topLevelOnly = opts?.topLevelOnly ?? false;
+
+  const conditions: string[] = ["surface_id = ?"];
+  const params: (string | number | null)[] = [surfaceId];
+
+  if (status !== "all") {
+    conditions.push("status = ?");
+    params.push(status);
+  }
+
+  if (topLevelOnly) {
+    conditions.push("parent_comment_id IS NULL");
+  }
+
+  const where = conditions.join(" AND ");
+  const rows = rawAll<CommentRow>(
+    /*sql*/ `SELECT * FROM document_comments WHERE ${where} ORDER BY created_at ASC`,
+    ...params,
+  );
+
+  return rows.map(mapRowToComment);
+}
+
+export function resolveComment(id: string, resolvedBy: string): boolean {
+  const now = Date.now();
+  const changes = rawRun(
+    /*sql*/ `UPDATE document_comments
+      SET status = 'resolved', resolved_by = ?, resolved_at = ?, updated_at = ?
+      WHERE id = ?`,
+    resolvedBy,
+    now,
+    now,
+    id,
+  );
+  if (changes > 0) {
+    log.info({ id, resolvedBy }, "Resolved comment");
+  }
+  return changes > 0;
+}
+
+export function reopenComment(id: string): boolean {
+  const now = Date.now();
+  const changes = rawRun(
+    /*sql*/ `UPDATE document_comments
+      SET status = 'open', resolved_by = NULL, resolved_at = NULL, updated_at = ?
+      WHERE id = ?`,
+    now,
+    id,
+  );
+  if (changes > 0) {
+    log.info({ id }, "Reopened comment");
+  }
+  return changes > 0;
+}
+
+export function updateCommentContent(id: string, content: string): boolean {
+  const now = Date.now();
+  const changes = rawRun(
+    /*sql*/ `UPDATE document_comments SET content = ?, updated_at = ? WHERE id = ?`,
+    content,
+    now,
+    id,
+  );
+  if (changes > 0) {
+    log.info({ id }, "Updated comment content");
+  }
+  return changes > 0;
+}
+
+export function deleteComment(id: string): boolean {
+  // Replies cascade-delete via the self-referential FK on parent_comment_id.
+  const changes = rawRun(
+    /*sql*/ `DELETE FROM document_comments WHERE id = ?`,
+    id,
+  );
+  if (changes > 0) {
+    log.info({ id }, "Deleted comment and its replies");
+  }
+  return changes > 0;
+}
+
+export function getCommentCountForDocument(surfaceId: string): number {
+  const row = rawGet<{ count: number }>(
+    /*sql*/ `SELECT COUNT(*) AS count FROM document_comments
+      WHERE surface_id = ? AND status = 'open'`,
+    surfaceId,
+  );
+  return row?.count ?? 0;
+}