feat: live editing comments in suggestions in new UI

Author: florentc

frontend/src/components/suggestions/Comment.module.css

@@ -0,0 +1,22 @@
+.textarea {
+  width: 100%;
+  min-height: 6em;
+  resize: vertical;
+  transition: background-color 0.2s ease;
+}
+
+.pending {
+  background-color: var(--light-yellow);
+}
+
+.saving {
+  background-color: var(--light-yellow);
+}
+
+.saved {
+  background-color: var(--light-green);
+}
+
+.error {
+  background-color: var(--light-red);
+}

frontend/src/components/suggestions/Comment.tsx

@@ -1,11 +1,70 @@
+import { useEffect, useRef, useState } from "preact/hooks";
+import { useCommentMutation } from "@/hooks/useComment";
+import styles from "./Comment.module.css";
+
+type SaveState = "idle" | "pending" | "saving" | "saved" | "error";
+
 type Props = {
-  comment: string;
+  suggestionId: number;
+  comment: string | null;
+  canEdit: boolean;
 };
 
-export function Comment({ comment }: Props) {
+const DEBOUNCE_SAVE_MS = 500;
+const DEBOUNCE_CLEAR_SAVED_FEEDBACK_MS = 2000;
+
+export function Comment({ suggestionId, comment, canEdit }: Props) {
+  const [value, setValue] = useState(comment ?? "");
+  const [saveState, setSaveState] = useState<SaveState>("idle");
+  const debounceRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const savedTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const mutation = useCommentMutation(suggestionId);
+
+  // Sync if the prop changes externally (e.g. parent re-fetches)
+  useEffect(() => {
+    setValue(comment ?? "");
+  }, [comment]);
+
+  function handleChange(e: Event) {
+    const next = (e.target as HTMLTextAreaElement).value;
+    setValue(next);
+    setSaveState("pending");
+
+    if (debounceRef.current) clearTimeout(debounceRef.current);
+    if (savedTimeoutRef.current) clearTimeout(savedTimeoutRef.current);
+
+    debounceRef.current = setTimeout(() => {
+      setSaveState("saving");
+      mutation.mutate(
+        { id: suggestionId, data: { comment: next } },
+        {
+          onSuccess: () => {
+            setSaveState("saved");
+            savedTimeoutRef.current = setTimeout(
+              () => setSaveState("idle"),
+              DEBOUNCE_CLEAR_SAVED_FEEDBACK_MS,
+            );
+          },
+          onError: () => {
+            setSaveState("error");
+          },
+        },
+      );
+    }, DEBOUNCE_SAVE_MS);
+  }
+
+  const stateClass = styles[saveState];
+
   return (
-    <textarea className="box rounded border monospace" disabled>
-      {comment}
-    </textarea>
+    <textarea
+      className={`box rounded border monospace ${styles.textarea} ${stateClass}`}
+      value={value}
+      onInput={handleChange}
+      placeholder="Free comment: context, additional info, dismissal reason, etc."
+      disabled={!canEdit}
+      maxLength={1000}
+      data-save-state={saveState}
+    />
   );
 }

frontend/src/components/suggestions/Suggestion.tsx

@@ -1,5 +1,6 @@
 import { Link } from "wouter-preact";
 import type { Suggestion as SuggestionType } from "@/api/generated/models";
+import { useAuth } from "@/hooks/useAuth";
 import { ActivityLog } from "./ActivityLog";
 import { AffectedProductsList } from "./AffectedProductsList";
 import { CategorizedMaintainersList } from "./CategorizedMaintainersList";
@@ -30,6 +31,9 @@ export function Suggestion({ suggestion }: Props) {
     categorized_url_references,
   } = suggestion;
 
+  const { user } = useAuth();
+  const canEdit = Boolean(user?.is_committer || user?.is_admin);
+
   const nvdUrl = `https://nvd.nist.gov/vuln/detail/${encodeURIComponent(cve_id)}`;
 
   return (
@@ -88,7 +92,9 @@ export function Suggestion({ suggestion }: Props) {
       )}
 
       {/* Comment */}
-      {comment && comment.length > 0 && <Comment comment={comment} />}
+      {(comment || canEdit) && (
+        <Comment suggestionId={id} comment={comment ?? null} canEdit={canEdit} />
+      )}
     </article>
   );
 }

frontend/src/hooks/useComment.ts

@@ -0,0 +1,19 @@
+import { useQueryClient } from "@tanstack/react-query";
+import { getGetSuggestionQueryKey, useUpdateSuggestionComment } from "@/api/generated/endpoints";
+import type { Suggestion } from "@/api/generated/models";
+
+export function useCommentMutation(suggestionId: number) {
+  const queryClient = useQueryClient();
+
+  return useUpdateSuggestionComment({
+    mutation: {
+      onSuccess: (data) => {
+        const queryKey = getGetSuggestionQueryKey(suggestionId);
+        queryClient.setQueryData<Suggestion>(queryKey, (prev) => {
+          if (!prev) return prev;
+          return { ...prev, comment: data.comment ?? null };
+        });
+      },
+    },
+  });
+}

src/api/suggestions/serializers.py

@@ -13,6 +13,18 @@
 from shared.models.linkage import CVEDerivationClusterProposal
 
 
+class SuggestionCommentSerializer(serializers.Serializer):
+    """Serializer for reading or updating a suggestion comment."""
+
+    comment = serializers.CharField(
+        allow_null=True,
+        allow_blank=True,
+        required=True,
+        max_length=1000,
+        help_text="Free-text comment. Set to empty string to clear.",
+    )
+
+
 class MetricHumanReadableItemSerializer(serializers.Serializer):
     label = serializers.CharField()
     value = serializers.CharField()

src/api/suggestions/views.py

@@ -11,6 +11,7 @@
 from api.serializers import ErrorDetailSerializer
 from api.suggestions.serializers import (
     ActivityLogEntrySerializer,
+    SuggestionCommentSerializer,
     SuggestionSerializer,
     folded_event_to_dict,
 )
@@ -134,3 +135,40 @@ def activity_log(self, request: Request, pk: int) -> Response:
         data = [folded_event_to_dict(e) for e in folded]
         serializer = ActivityLogEntrySerializer(data, many=True)
         return Response(serializer.data)
+
+    @extend_schema(
+        methods=["get"],
+        operation_id="getSuggestionComment",
+        description="Get the current comment for a suggestion.",
+        responses={200: SuggestionCommentSerializer, 404: ErrorDetailSerializer},
+    )
+    @extend_schema(
+        methods=["patch"],
+        operation_id="updateSuggestionComment",
+        description="Update the comment for a suggestion. Send an empty string to clear it.",
+        request=SuggestionCommentSerializer,
+        responses={
+            200: SuggestionCommentSerializer,
+            400: ErrorDetailSerializer,
+            403: ErrorDetailSerializer,
+            404: ErrorDetailSerializer,
+        },
+    )
+    @action(
+        detail=True,
+        methods=["get", "patch"],
+        url_path="comment",
+        serializer_class=SuggestionCommentSerializer,
+    )
+    def comment(self, request: Request, pk: int) -> Response:
+        if request.method == "GET":
+            instance = self.get_object()
+            return Response(self.get_serializer(instance).data)
+        elif request.method == "PATCH":
+            serializer = self.get_serializer(data=request.data)
+            serializer.is_valid(raise_exception=True)
+            instance = self.get_object()
+            instance.set_comment(serializer.validated_data["comment"])
+            return Response(self.get_serializer(instance).data)
+        else:
+            raise MethodNotAllowed(request.method)

src/api/tests/test_suggestion_comment.py

@@ -0,0 +1,100 @@
+from collections.abc import Callable
+
+from django.contrib.auth.models import User
+from rest_framework.reverse import reverse
+from rest_framework.test import APIClient
+
+from shared.models.linkage import CVEDerivationClusterProposal
+
+
+def url(id: int) -> str:
+    return reverse("cvederivationclusterproposal-comment", kwargs={"pk": id})
+
+
+def test_get_comment_anonymous_no_comment(
+    cached_suggestion: CVEDerivationClusterProposal,
+) -> None:
+    client = APIClient()
+    response = client.get(url(cached_suggestion.pk))
+    assert response.status_code == 200
+    assert response.data == {"comment": None}
+
+
+def test_get_comment_anonymous_with_comment(
+    make_cached_suggestion: Callable[..., CVEDerivationClusterProposal],
+) -> None:
+    suggestion = make_cached_suggestion(comment="foo")
+    client = APIClient()
+    response = client.get(url(suggestion.pk))
+    assert response.status_code == 200
+    assert response.data == {"comment": "foo"}
+
+
+def test_get_comment_not_found(cached_suggestion: CVEDerivationClusterProposal) -> None:
+    client = APIClient()
+    response = client.get(url(cached_suggestion.pk + 1))
+    assert response.status_code == 404
+
+
+def test_patch_comment_unauthenticated(
+    cached_suggestion: CVEDerivationClusterProposal,
+) -> None:
+    client = APIClient()
+    response = client.patch(
+        url(cached_suggestion.pk), {"comment": "foo"}, format="json"
+    )
+    assert response.status_code == 401
+
+
+def test_patch_comment_non_comitter(
+    cached_suggestion: CVEDerivationClusterProposal,
+    user: User,
+) -> None:
+    client = APIClient()
+    client.force_login(user)
+    response = client.patch(
+        url(cached_suggestion.pk), {"comment": "foo"}, format="json"
+    )
+    assert response.status_code == 403
+
+
+def test_patch_comment_sets_value(
+    cached_suggestion: CVEDerivationClusterProposal,
+    committer: User,
+) -> None:
+    client = APIClient()
+    client.force_login(committer)
+    response = client.patch(
+        url(cached_suggestion.pk), {"comment": "foo"}, format="json"
+    )
+    assert response.status_code == 200
+    assert response.data == {"comment": "foo"}
+    response = client.get(url(cached_suggestion.pk))
+    assert response.status_code == 200
+    assert response.data == {"comment": "foo"}
+
+
+def test_patch_comment_clears_with_empty_string(
+    make_cached_suggestion: Callable[..., CVEDerivationClusterProposal],
+    committer: User,
+) -> None:
+    suggestion = make_cached_suggestion(comment="foo")
+    client = APIClient()
+    client.force_login(committer)
+    response = client.patch(url(suggestion.pk), {"comment": ""}, format="json")
+    assert response.status_code == 200
+    assert response.data == {"comment": None}
+    response = client.get(url(suggestion.pk))
+    assert response.status_code == 200
+    assert response.data == {"comment": None}
+
+
+def test_patch_comment_not_found(
+    cached_suggestion: CVEDerivationClusterProposal, committer: User
+) -> None:
+    client = APIClient()
+    client.force_login(committer)
+    response = client.patch(
+        url(cached_suggestion.pk + 1), {"comment": "foo"}, format="json"
+    )
+    assert response.status_code == 404

src/shared/models/linkage.py

@@ -182,6 +182,11 @@ def restore_package(self, package: str) -> None:
             overlay_type=PackageOverlay.Type.IGNORED,
         ).delete()
 
+    def set_comment(self, comment: str | None) -> None:
+        """Update the free-text comment independently of status changes."""
+        self.comment = comment or None
+        self.save(update_fields=["comment"])
+
     def change_status(
         self,
         status: SuggestionStatus,

src/shared/tests/conftest.py

@@ -324,6 +324,7 @@ def wrapped(
             drv: ProvenanceFlags.PACKAGE_NAME_MATCH
         },
         status: CVEDerivationClusterProposal.Status = CVEDerivationClusterProposal.Status.PENDING,
+        comment: str | None = None,
         rejection_reason: CVEDerivationClusterProposal.RejectionReason | None = None,
         in_issue_draft: bool = False,
         age: timedelta = timedelta(0),
@@ -334,6 +335,7 @@ def wrapped(
             rejection_reason=rejection_reason,
             in_issue_draft=in_issue_draft,
             cve=container.cve,
+            comment=comment,
             algorithm_version=algorithm_version
             if algorithm_version is not None
             else CVEDerivationClusterProposal.CURRENT_ALGORITHM_VERSION,

src/webview/tests/conftest.py

@@ -63,6 +63,15 @@ def as_staff(
         yield page
 
 
+@pytest.fixture
+def as_committer(
+    logged_in_as: Callable[..., AbstractContextManager[Page]],
+    committer: User,
+) -> Generator[Page]:
+    with logged_in_as(committer) as page:
+        yield page
+
+
 @pytest.fixture
 def logged_in_as(
     live_server: LiveServer,