diff --git a/server/migrations/20260514000000-cascade-resolved-to-reply-comments.js b/server/migrations/20260514000000-cascade-resolved-to-reply-comments.js new file mode 100644 index 0000000000..8c41c22563 --- /dev/null +++ b/server/migrations/20260514000000-cascade-resolved-to-reply-comments.js @@ -0,0 +1,20 @@ +"use strict"; + +module.exports = { + async up(queryInterface) { + await queryInterface.sequelize.query(` + UPDATE comments AS reply + SET "resolvedAt" = parent."resolvedAt", + "resolvedById" = parent."resolvedById" + FROM comments AS parent + WHERE reply."parentCommentId" = parent.id + AND parent."resolvedAt" IS NOT NULL + AND reply."resolvedAt" IS NULL; + `); + }, + + async down() { + // No-op: the inherited resolved state on replies is now load-bearing for + // the unresolved commentCount counter cache, so it cannot safely be undone. + }, +}; diff --git a/server/models/Comment.test.ts b/server/models/Comment.test.ts index 1b5799d530..15d0a76a7b 100644 --- a/server/models/Comment.test.ts +++ b/server/models/Comment.test.ts @@ -186,4 +186,103 @@ describe("Comment", () => { expect(() => comment.unresolve()).toThrow(); }); }); + + describe("cascade resolved state", () => { + it("propagates resolvedAt to existing replies when the thread is resolved", async () => { + const user = await buildUser(); + const document = await buildDocument({ + userId: user.id, + teamId: user.teamId, + }); + const thread = await buildComment({ + userId: user.id, + documentId: document.id, + }); + const reply = await buildComment({ + userId: user.id, + documentId: document.id, + parentCommentId: thread.id, + }); + + thread.resolve(user); + await thread.save(); + + await reply.reload(); + expect(reply.resolvedAt).toEqual(thread.resolvedAt); + expect(reply.resolvedById).toEqual(user.id); + }); + + it("clears resolvedAt on replies when the thread is unresolved", async () => { + const user = await buildUser(); + const document = await buildDocument({ + userId: user.id, + teamId: user.teamId, + }); + const thread = await buildComment({ + userId: user.id, + documentId: document.id, + }); + const reply = await buildComment({ + userId: user.id, + documentId: document.id, + parentCommentId: thread.id, + }); + + thread.resolve(user); + await thread.save(); + thread.unresolve(); + await thread.save(); + + await reply.reload(); + expect(reply.resolvedAt).toBeNull(); + expect(reply.resolvedById).toBeNull(); + }); + + it("inherits resolved state when a reply is created on a resolved thread", async () => { + const user = await buildUser(); + const document = await buildDocument({ + userId: user.id, + teamId: user.teamId, + }); + const thread = await buildComment({ + userId: user.id, + documentId: document.id, + }); + thread.resolve(user); + await thread.save(); + + const reply = await buildComment({ + userId: user.id, + documentId: document.id, + parentCommentId: thread.id, + }); + + expect(reply.resolvedAt).toEqual(thread.resolvedAt); + expect(reply.resolvedById).toEqual(user.id); + }); + + it("rejects replies to comments in a different document", async () => { + const user = await buildUser(); + const document = await buildDocument({ + userId: user.id, + teamId: user.teamId, + }); + const otherDocument = await buildDocument({ + userId: user.id, + teamId: user.teamId, + }); + const thread = await buildComment({ + userId: user.id, + documentId: otherDocument.id, + }); + + await expect( + buildComment({ + userId: user.id, + documentId: document.id, + parentCommentId: thread.id, + }) + ).rejects.toThrow("Parent comment must belong to the same document"); + }); + }); }); diff --git a/server/models/Comment.ts b/server/models/Comment.ts index 59d0a79ef6..5129de6e60 100644 --- a/server/models/Comment.ts +++ b/server/models/Comment.ts @@ -1,20 +1,29 @@ import { Node } from "prosemirror-model"; -import type { InferAttributes, InferCreationAttributes } from "sequelize"; +import type { + CreateOptions, + InferAttributes, + InferCreationAttributes, + InstanceUpdateOptions, +} from "sequelize"; import { DataType, BelongsTo, + BeforeCreate, ForeignKey, Column, Table, Length, DefaultScope, AfterDestroy, + AfterUpdate, } from "sequelize-typescript"; import type { ProsemirrorData, ReactionSummary } from "@shared/types"; import { ProsemirrorHelper } from "@shared/utils/ProsemirrorHelper"; import { CommentValidation } from "@shared/validations"; import { commentSchema } from "@server/editor"; import { ValidationError } from "@server/errors"; +import { CacheHelper } from "@server/utils/CacheHelper"; +import { RedisPrefixHelper } from "@server/utils/RedisPrefixHelper"; import Document from "./Document"; import User from "./User"; import { type HookContext } from "./base/Model"; @@ -143,6 +152,78 @@ class Comment extends ParanoidModel< // hooks + // A reply created on an already-resolved thread inherits the parent's + // resolved state so the resolvedAt column alone can answer "is this thread + // resolved?" — keeping read queries simple and the counter cache index-only. + @BeforeCreate + public static async inheritResolvedFromParent( + model: Comment, + options: CreateOptions> + ) { + if (!model.parentCommentId || model.resolvedAt) { + return; + } + const parent = await this.unscoped().findOne({ + where: { + id: model.parentCommentId, + documentId: model.documentId, + }, + transaction: options.transaction, + lock: options.transaction + ? { level: options.transaction.LOCK.UPDATE, of: this } + : undefined, + }); + if (!parent) { + throw ValidationError("Parent comment must belong to the same document"); + } + if (parent?.resolvedAt) { + model.resolvedAt = parent.resolvedAt; + model.resolvedById = parent.resolvedById; + } + } + + // When a thread root is resolved or unresolved, propagate the same state to + // its replies and invalidate the document's commentCount counter cache. + @AfterUpdate + public static async cascadeResolvedToReplies( + model: Comment, + options: InstanceUpdateOptions> + ) { + if (!model.changed("resolvedAt")) { + return; + } + + if (model.parentCommentId === null) { + await this.update( + { + resolvedAt: model.resolvedAt, + resolvedById: model.resolvedById, + }, + { + where: { parentCommentId: model.id, documentId: model.documentId }, + transaction: options.transaction, + hooks: false, + } + ); + } + + const invalidate = () => + CacheHelper.removeData( + RedisPrefixHelper.getCounterCacheKey( + "Document", + "unresolvedComments", + model.documentId + ) + ); + + if (options.transaction) { + const transaction = options.transaction.parent || options.transaction; + transaction.afterCommit(invalidate); + } else { + await invalidate(); + } + } + @AfterDestroy public static async deleteChildComments(model: Comment, ctx: HookContext) { const { transaction } = ctx; diff --git a/server/models/Document.test.ts b/server/models/Document.test.ts index e8636b5dc6..11372c37dd 100644 --- a/server/models/Document.test.ts +++ b/server/models/Document.test.ts @@ -7,6 +7,8 @@ import { buildDocument, buildDraftDocument, buildCollection, + buildComment, + buildResolvedComment, buildTeam, buildUser, buildGuestUser, @@ -352,3 +354,100 @@ describe("tasks", () => { expect(newTasks.total).toBe(3); }); }); + +describe("commentCount", () => { + it("returns 0 for a document with no comments", async () => { + const document = await buildDocument(); + expect(await document.commentCount).toEqual(0); + }); + + it("counts unresolved threads and their replies", async () => { + const document = await buildDocument(); + const thread = await buildComment({ + documentId: document.id, + userId: document.createdById, + }); + await buildComment({ + documentId: document.id, + userId: document.createdById, + parentCommentId: thread.id, + }); + expect(await document.commentCount).toEqual(2); + }); + + it("excludes resolved threads and their replies", async () => { + const document = await buildDocument(); + const user = await buildUser({ teamId: document.teamId }); + const resolved = await buildResolvedComment(user, { + documentId: document.id, + userId: user.id, + }); + await buildComment({ + documentId: document.id, + userId: user.id, + parentCommentId: resolved.id, + }); + await buildComment({ + documentId: document.id, + userId: user.id, + }); + expect(await document.commentCount).toEqual(1); + }); + + it("invalidates the cached count when a comment is destroyed", async () => { + const document = await buildDocument(); + const comment = await buildComment({ + documentId: document.id, + userId: document.createdById, + }); + await buildComment({ + documentId: document.id, + userId: document.createdById, + }); + + expect(await document.commentCount).toEqual(2); + + await comment.destroy(); + + expect(await document.commentCount).toEqual(1); + }); + + it("invalidates the cached count when a thread is resolved", async () => { + const document = await buildDocument(); + const user = await buildUser({ teamId: document.teamId }); + const thread = await buildComment({ + documentId: document.id, + userId: user.id, + }); + await buildComment({ + documentId: document.id, + userId: user.id, + parentCommentId: thread.id, + }); + + // Prime the cache. + expect(await document.commentCount).toEqual(2); + + thread.resolve(user); + await thread.save(); + + expect(await document.commentCount).toEqual(0); + }); + + it("invalidates the cached count when a resolved thread is unresolved", async () => { + const document = await buildDocument(); + const user = await buildUser({ teamId: document.teamId }); + const thread = await buildResolvedComment(user, { + documentId: document.id, + userId: user.id, + }); + + // Prime the cache (resolved thread is excluded). + expect(await document.commentCount).toEqual(0); + + thread.unresolve(); + await thread.save(); + + expect(await document.commentCount).toEqual(1); + }); +}); diff --git a/server/models/Document.ts b/server/models/Document.ts index eac22c4a05..5d8c1371cc 100644 --- a/server/models/Document.ts +++ b/server/models/Document.ts @@ -51,6 +51,7 @@ import { DocumentValidation } from "@shared/validations"; import { InvalidRequestError, ValidationError } from "@server/errors"; import { generateUrlId } from "@server/utils/url"; import Collection from "./Collection"; +import Comment from "./Comment"; import FileOperation from "./FileOperation"; import Group from "./Group"; import GroupMembership from "./GroupMembership"; @@ -64,6 +65,7 @@ import User from "./User"; import UserMembership from "./UserMembership"; import View from "./View"; import ArchivableModel from "./base/ArchivableModel"; +import { CounterCache } from "./decorators/CounterCache"; import Fix from "./decorators/Fix"; import { DocumentHelper } from "./helpers/DocumentHelper"; import IsHexColor from "./validators/IsHexColor"; @@ -678,6 +680,13 @@ class Document extends ArchivableModel< @HasMany(() => View) views: View[]; + @CounterCache(() => Comment, { + as: "unresolvedComments", + foreignKey: "documentId", + where: { resolvedAt: { [Op.is]: null } }, + }) + commentCount: Promise; + /** * Returns an array of unique userIds that are members of a document * either via group or direct membership. diff --git a/server/presenters/document.ts b/server/presenters/document.ts index 45e363787e..9ea9f1bafa 100644 --- a/server/presenters/document.ts +++ b/server/presenters/document.ts @@ -18,6 +18,9 @@ type Options = { includeData?: boolean; /** Include the updatedAt timestamp for public documents. */ includeUpdatedAt?: boolean; + /** Include the unresolved comment count. Each call triggers a Redis lookup + * so only enable when the consumer needs the signal (e.g. MCP). */ + includeCommentCount?: boolean; /** Array of backlink document IDs to include in the response. */ backlinkIds?: string[]; }; @@ -112,6 +115,9 @@ async function presentDocument( res.templateId = document.templateId; res.insightsEnabled = document.insightsEnabled; res.popularityScore = document.popularityScore; + if (options.includeCommentCount) { + res.commentCount = await document.commentCount; + } res.sourceMetadata = document.sourceMetadata ? { importedAt: source?.createdAt ?? document.createdAt, diff --git a/server/tools/documents.test.ts b/server/tools/documents.test.ts index 826ba1a428..bdd0e3f74e 100644 --- a/server/tools/documents.test.ts +++ b/server/tools/documents.test.ts @@ -35,6 +35,9 @@ describe("list_documents", () => { (d: { document: { id: string } }) => d.document.id === document.id ) as { document: { url: string } }; expect(match.document.url).toMatch(/^https?:\/\//); + expect( + (match.document as { commentCount?: number }).commentCount + ).toBeUndefined(); }); it("filters by collection", async () => { diff --git a/server/tools/documents.ts b/server/tools/documents.ts index 30bde79273..e1f27eb544 100644 --- a/server/tools/documents.ts +++ b/server/tools/documents.ts @@ -8,7 +8,10 @@ import { Op } from "sequelize"; import { Collection, Document } from "@server/models"; import { sequelize } from "@server/storage/database"; import { authorize, can } from "@server/policies"; -import { presentDocument, presentNavigationNode } from "@server/presenters"; +import { + presentDocument as presentDocumentBase, + presentNavigationNode, +} from "@server/presenters"; import AuthenticationHelper from "@shared/helpers/AuthenticationHelper"; import { UrlHelper } from "@shared/utils/UrlHelper"; import { @@ -26,6 +29,26 @@ import { import { TextEditMode } from "@shared/types"; import SearchProviderManager from "@server/utils/SearchProviderManager"; +/** + * Presents a document for a tool response. Adds MCP-specific fields + * on top of the standard document presenter. + * + * @param document - the document to present. + * @param options - optional presenter options + * @returns the presented document object. + */ +export function presentDocument( + document: Document, + options: { + includeData?: boolean; + includeText?: boolean; + includeUpdatedAt?: boolean; + includeCommentCount?: boolean; + } = {} +) { + return presentDocumentBase(undefined, document, options); +} + /** * Registers document-related MCP tools on the given server, filtered by * the OAuth scopes granted to the current token. @@ -135,7 +158,7 @@ export function documentTools(server: McpServer, scopes: string[]) { filteredResults.map(async (result) => { const doc = pathToUrl( user.team, - await presentDocument(undefined, result.document, { + await presentDocument(result.document, { includeData: false, includeText: false, }) @@ -156,7 +179,7 @@ export function documentTools(server: McpServer, scopes: string[]) { if (exactMatch) { const doc = pathToUrl( user.team, - await presentDocument(undefined, exactMatch, { + await presentDocument(exactMatch, { includeData: false, includeText: false, }) @@ -199,7 +222,7 @@ export function documentTools(server: McpServer, scopes: string[]) { documents.map(async (document) => { const doc = pathToUrl( user.team, - await presentDocument(undefined, document, { + await presentDocument(document, { includeData: false, includeText: false, }) @@ -353,7 +376,7 @@ export function documentTools(server: McpServer, scopes: string[]) { }); const [{ text, ...attributes }, breadcrumb] = await Promise.all([ - presentDocument(undefined, document, { + presentDocument(document, { includeData: false, includeText: true, includeUpdatedAt: true, @@ -489,7 +512,7 @@ export function documentTools(server: McpServer, scopes: string[]) { documents.map(async (document) => { const doc = pathToUrl( user.team, - await presentDocument(undefined, document, { + await presentDocument(document, { includeData: false, includeText: false, }) @@ -603,7 +626,7 @@ export function documentTools(server: McpServer, scopes: string[]) { } const [{ text, ...attributes }, breadcrumb] = await Promise.all([ - presentDocument(undefined, updated, { + presentDocument(updated, { includeData: false, includeText: true, includeUpdatedAt: true, diff --git a/server/tools/fetch.test.ts b/server/tools/fetch.test.ts index 3209a4d7b0..ddf94b7561 100644 --- a/server/tools/fetch.test.ts +++ b/server/tools/fetch.test.ts @@ -1,4 +1,9 @@ -import { buildCollection, buildDocument } from "@server/test/factories"; +import { + buildCollection, + buildComment, + buildDocument, + buildResolvedComment, +} from "@server/test/factories"; import { getTestServer } from "@server/test/support"; import { buildOAuthUser, callMcpTool } from "@server/test/McpHelper"; @@ -55,4 +60,38 @@ describe("fetch", () => { // Second content is markdown text expect(res!.result!.content![1].text).toContain("Hello"); }); + + it("returns unresolved commentCount on documents", async () => { + const { user, accessToken } = await buildOAuthUser(); + const collection = await buildCollection({ + teamId: user.teamId, + userId: user.id, + }); + const document = await buildDocument({ + teamId: user.teamId, + userId: user.id, + collectionId: collection.id, + }); + const thread = await buildComment({ + documentId: document.id, + userId: user.id, + }); + await buildComment({ + documentId: document.id, + userId: user.id, + parentCommentId: thread.id, + }); + await buildResolvedComment(user, { + documentId: document.id, + userId: user.id, + }); + + const res = await callMcpTool(server, accessToken, "fetch", { + resource: "document", + id: document.id, + }); + + const metadata = JSON.parse(res!.result!.content![0].text ?? "{}"); + expect(metadata.document.commentCount).toEqual(2); + }); }); diff --git a/server/tools/fetch.ts b/server/tools/fetch.ts index ffb490c604..c3acd98c66 100644 --- a/server/tools/fetch.ts +++ b/server/tools/fetch.ts @@ -6,11 +6,11 @@ import { authorize, can } from "@server/policies"; import { AuthorizationError } from "@server/errors"; import { presentCollection, - presentDocument, presentNavigationNode, presentUser, } from "@server/presenters"; import AuthenticationHelper from "@shared/helpers/AuthenticationHelper"; +import { presentDocument } from "./documents"; import { error, success, @@ -119,10 +119,11 @@ export function fetchTool(server: McpServer, scopes: string[]) { authorize(actor, "read", document); const [{ text, ...attributes }, breadcrumb] = await Promise.all([ - presentDocument(undefined, document, { + presentDocument(document, { includeData: false, includeText: true, includeUpdatedAt: true, + includeCommentCount: true, }), getDocumentBreadcrumb(document, actor), ]);