feat(action): add comment-on-clean input to suppress success comments

action.yml

@@ -20,6 +20,9 @@ inputs:
   comment:
     description: "Create or update a sticky pull request summary comment. Automatically skipped when the pull request changes no React-eligible files (`.tsx`/`.jsx` or framework entry files)."
     default: "true"
+  comment-on-clean:
+    description: "When comment is enabled, whether to post a comment when the scan finds no issues. Set to false to only comment when there are issues to fix, reducing PR noise. Existing comments are still updated."
+    default: "true"
   review-comments:
     description: "Post inline review comments on the changed lines that triggered diagnostics (pull requests only)."
     default: "true"
@@ -386,6 +389,8 @@ runs:
       env:
         REACT_DOCTOR_COMMENT_FILE: ${{ steps.render.outputs.comment-file }}
         REACT_DOCTOR_SKIPPED: ${{ steps.render.outputs.skipped }}
+        REACT_DOCTOR_CLEAN: ${{ steps.render.outputs.clean }}
+        REACT_DOCTOR_COMMENT_ON_CLEAN: ${{ inputs.comment-on-clean }}
       with:
         script: |
           const fs = require("fs");
@@ -401,6 +406,12 @@ runs:
           // changes were reverted out of the PR.
           const skipped = process.env.REACT_DOCTOR_SKIPPED === "true";
 
+          // A clean scan (no issues found) can optionally skip creating new
+          // comments via the `comment-on-clean` input, reducing PR noise. Existing
+          // comments are still updated so stale findings don't linger.
+          const clean = process.env.REACT_DOCTOR_CLEAN === "true";
+          const commentOnClean = process.env.REACT_DOCTOR_COMMENT_ON_CLEAN !== "false";
+
           const marker = "<!-- react-doctor:summary -->";
           try {
             const { data: comments } = await github.rest.issues.listComments({
@@ -410,6 +421,7 @@ runs:
             });
             const previous = comments.find((comment) => comment.body?.startsWith(marker));
             if (skipped && !previous) return;
+            if (clean && !commentOnClean && !previous) return;
             if (previous) {
               await github.rest.issues.updateComment({
                 ...context.repo,

packages/react-doctor/tests/github-action-comment.test.ts

@@ -356,6 +356,7 @@ describe("render-github-action-comment", () => {
     expect(comment).not.toContain("No React Doctor issues found");
     expect(comment).not.toContain("found no issues");
     expect(outputs).toContain("skipped=true");
+    expect(outputs).toContain("clean=false");
   });
 
   it("marks a diff scan whose changed files examined zero eligible files as skipped", () => {
@@ -378,6 +379,7 @@ describe("render-github-action-comment", () => {
 
     expect(comment).toContain("React Doctor skipped this pull request");
     expect(outputs).toContain("skipped=true");
+    expect(outputs).toContain("clean=false");
   });
 
   it("does NOT skip a clean scan of real React changes (eligible files examined)", () => {
@@ -401,6 +403,14 @@ describe("render-github-action-comment", () => {
     expect(comment).toContain("**React Doctor** found no issues. 🎉");
     expect(comment).not.toContain("skipped this pull request");
     expect(outputs).toContain("skipped=false");
+    expect(outputs).toContain("clean=true");
+  });
+
+  it("marks a scan with issues as not clean", () => {
+    const { outputs } = runRenderer(buildReport());
+
+    expect(outputs).toContain("skipped=false");
+    expect(outputs).toContain("clean=false");
   });
 
   it("does NOT skip a full-scope scan with no projects (clean success, not a no-op)", () => {

scripts/render-github-action-comment.mjs

@@ -401,6 +401,14 @@ const isSkippedScan = (report) => {
   return (report.projects ?? []).every((project) => project.scannedFileCount === 0);
 };
 
+const isCleanScan = (report) => {
+  if (!report.ok) return false;
+  if (isSkippedScan(report)) return false;
+  if ((report.summary?.totalDiagnosticCount ?? 0) > 0) return false;
+  if (hasIncompleteChecks(report)) return false;
+  return true;
+};
+
 // Unified body for every successful scan (baseline, diff, full). The lead line
 // adapts to the mode; the error/warning lists are shared.
 const buildIssuesBody = (report) => {
@@ -434,6 +442,7 @@ if (!report) {
   process.exit(0);
 }
 const skipped = isSkippedScan(report);
+const clean = isCleanScan(report);
 const body = skipped ? buildSingleLineBody(COPY.skipped) : buildCommentBody(report);
 
 if (commentPath) {
@@ -445,6 +454,7 @@ if (commentPath) {
 // The Action reads this to suppress the sticky PR comment (it still mirrors the
 // body into the job summary + commit status, which read "skipped").
 appendOutput("skipped", skipped ? "true" : "false");
+appendOutput("clean", clean ? "true" : "false");
 
 appendOutput(
   "score",