From 5576b4ff342489e93c7bc8a9e4a41be15b32d47a Mon Sep 17 00:00:00 2001
From: Denis Angell <dangell@transia.co>
Date: Thu, 14 May 2026 10:40:54 +0200
Subject: [PATCH] fix(doc-agent): shape review comments for GitHub
 createReviewComment API

---
 .github/scripts/doc-agent/src/review.ts | 14 ++++++++++++--
 .github/workflows/doc-review.yml        |  2 +-
 2 files changed, 13 insertions(+), 3 deletions(-)

diff --git a/.github/scripts/doc-agent/src/review.ts b/.github/scripts/doc-agent/src/review.ts
index 65cee7ecb6..73dc1ef7b4 100644
--- a/.github/scripts/doc-agent/src/review.ts
+++ b/.github/scripts/doc-agent/src/review.ts
@@ -214,9 +214,19 @@ export async function reviewDiff(args: readonly string[]): Promise<void> {
   const report = buildReport(files.length, results);
   const allIssues = results.flatMap((r) => r.issues);
 
+  // Shape inline comments for the GitHub pulls.createReviewComment API,
+  // which expects `path`/`line`/`body` rather than the internal field names.
+  const apiComments = allIssues.map((issue) => ({
+    path: issue.file,
+    line: issue.line,
+    body: issue.suggestedDoc
+      ? `**[${issue.severity}]** ${issue.message}\n\n\`\`\`cpp\n${issue.suggestedDoc}\n\`\`\``
+      : `**[${issue.severity}]** ${issue.message}`,
+  }));
+
   await writeFile('doc-review-report.md', report);
-  await writeFile('doc-review-comments.json', JSON.stringify(allIssues, null, 2));
+  await writeFile('doc-review-comments.json', JSON.stringify(apiComments, null, 2));
 
   console.log('\nReport: doc-review-report.md');
-  console.log(`Inline comments: doc-review-comments.json (${allIssues.length} issues)`);
+  console.log(`Inline comments: doc-review-comments.json (${apiComments.length} issues)`);
 }
diff --git a/.github/workflows/doc-review.yml b/.github/workflows/doc-review.yml
index a447eef796..7620285c73 100644
--- a/.github/workflows/doc-review.yml
+++ b/.github/workflows/doc-review.yml
@@ -20,7 +20,7 @@ defaults:
 
 jobs:
   review:
-    if: github.head_ref != 'dangell7/docs'
+    if: github.head_ref != 'dangell7/docs' && github.head_ref != 'dangell7/docs-full'
     runs-on: ubuntu-latest
     permissions:
       pull-requests: write