Format the API change comment as a C# diff for readability (#38084)

Author: AndriySvyryd

.agents/skills/run-apichief/SKILL.md

@@ -17,7 +17,7 @@ ApiChief can run against either a compiled assembly or a previously emitted base
 | `emit baseline` | Emit a JSON API baseline | `-o <file>` |
 | `emit summary` | Emit a human-readable API summary | `-o <file>`, `-x` |
 | `emit review` | Emit API review files | `-o <dir>`, `-n` |
-| `emit delta` | Emit a delta against an existing baseline | `<baseline-path>`, `-o <file>` |
+| `emit delta` | Emit a delta against an existing baseline, or markdown diff review files | `<baseline-path>`, `-o <file-or-dir>`, `--diff` |
 | `check breaking` | Fail if breaking changes exist vs. a baseline | `<baseline-path>` |
 
 Default to `emit baseline` if the user only asks to "run ApiChief".
@@ -105,6 +105,9 @@ Before running, report the selected TFM if it matters for the task.
 
 # Emit API review artifacts
 & $dotnet $apiChief $assemblyPath emit review -o ".\\artifacts\\tmp\\API.$name"
+
+# Emit GitHub-friendly markdown diff files against a baseline
+& $dotnet $apiChief $assemblyPath emit delta ".\\src\\$name\\$name.baseline.json" --diff -o ".\\artifacts\\tmp\\API.$name.Diff"
 ```
 
 `emit delta` also supports passing a `.json` file as the current input instead of a DLL.
@@ -124,4 +127,5 @@ After `emit baseline`:
 - show the chosen TFM(s)
 - report the output path(s)
 - for `check breaking`, state pass/fail
-- for `emit delta`, mention that exit code `0` means changes, `2` means no changes, and `-1` means an error
+- for `emit delta` and `emit delta --diff`, mention that exit code `0` means changes, `2` means no changes, and `-1` means an error
+- prefer `emit delta --diff` output because it generates ready-to-post ```diff fenced markdown split across per-type `.md` files

.github/workflows/api-review-baselines.yml

@@ -101,7 +101,7 @@ jobs:
         shell: bash
         run: ./restore.sh
 
-      - name: Build ApiChief and compute baseline deltas
+      - name: Build ApiChief and compute review diffs
         if: steps.detect.outputs.has_baselines == 'true'
         id: delta
         shell: bash
@@ -157,25 +157,36 @@ jobs:
                       return False
                   raise
 
-          def truncate(text: str, limit: int = 20000) -> str:
-              if len(text) <= limit:
-                  return text
-              return text[:limit] + '\n... (truncated)\n'
+          max_comment_length = 60000
+          comment_bodies: list[str] = []
+          current_body = ''
 
-          sections: list[str] = []
+          def append_section(section: str) -> None:
+              nonlocal current_body
+
+              if not current_body:
+                  current_body = section
+                  return
+
+              candidate = current_body + '\n\n' + section
+              if len(candidate) > max_comment_length:
+                  comment_bodies.append(current_body)
+                  current_body = section
+              else:
+                  current_body = candidate
 
           for index, file in enumerate(files):
               filename = file['filename']
               old_path = workdir / f'{index}.old.baseline.json'
               new_path = workdir / f'{index}.new.baseline.json'
-              delta_path = workdir / f'{index}.delta.json'
+              review_dir = workdir / f'{index}.review'
 
               old_exists = download_file(base_sha, filename, old_path)
               new_exists = download_file(target_sha, filename, new_path)
 
               if old_exists and new_exists:
                   result = subprocess.run(
-                      [dotnet, apichief, str(new_path), 'emit', 'delta', str(old_path), '-o', str(delta_path)],
+                      [dotnet, apichief, str(new_path), 'emit', 'delta', str(old_path), '--diff', '-o', str(review_dir)],
                       capture_output=True,
                       text=True,
                       check=False)
@@ -185,54 +196,77 @@ jobs:
 
                   if result.returncode != 0:
                       raise RuntimeError(
-                          f'ApiChief delta failed for {filename} with exit code {result.returncode}:\n'
+                          f'ApiChief delta diff failed for {filename} with exit code {result.returncode}:\n'
                           f'{result.stdout}\n{result.stderr}')
 
-                  delta_text = truncate(delta_path.read_text(encoding='utf-8'))
-                  sections.append(
-                      f"### `{filename}`\n\n"
-                      f"<details>\n<summary>Show delta</summary>\n\n```json\n{delta_text}\n```\n</details>")
+                  review_files = sorted(review_dir.rglob('*.md'))
+                  if not review_files:
+                      continue
+
+                  section = (
+                      f"## API review baseline changes for `{filename}`\n\n"
+                      'The diff below was generated by `ApiChief` between the base and selected PR versions.\n\n')
+
+                  for review_file in review_files:
+                      section += (
+                          f"{review_file.read_text(encoding='utf-8').rstrip()}\n\n")
+
+                  append_section(section.rstrip())
               elif new_exists:
-                  sections.append(f"### `{filename}`\n\nThis baseline file was **added** in the selected PR.")
+                  append_section(
+                      f"## API review baseline changes for `{filename}`\n\n"
+                      'This baseline file was **added** in the selected PR.')
               elif old_exists:
-                  sections.append(f"### `{filename}`\n\nThis baseline file was **removed** in the selected PR.")
+                  append_section(
+                      f"## API review baseline changes for `{filename}`\n\n"
+                      'This baseline file was **removed** in the selected PR.')
 
-          if not sections:
-              sections.append('No API deltas were produced for the modified baseline files.')
+          if not current_body:
+              append_section(
+                  '## API review baseline changes\n\n'
+                  'No API deltas were produced for the modified baseline files.')
 
-          body = (
-              '## API review baseline changes\n\n'
-              'This PR modified one or more `*.baseline.json` files. '
-              'The deltas below were generated by `ApiChief` between the base and selected PR versions.\n\n'
-              + '\n\n'.join(sections)
-          )
+          if current_body:
+              comment_bodies.append(current_body)
 
-          comment_path = workdir / 'comment.md'
-          comment_path.write_text(body[:65000], encoding='utf-8')
+          comments_dir = workdir / 'comments'
+          comments_dir.mkdir(parents=True, exist_ok=True)
+
+          for index, body in enumerate(comment_bodies, start=1):
+              comment_path = comments_dir / f'{index:03}.md'
+              comment_path.write_text(body.rstrip() + '\n', encoding='utf-8')
 
           with open(os.environ['GITHUB_OUTPUT'], 'a', encoding='utf-8') as output:
-              output.write(f'comment_path={comment_path}\n')
+              output.write(f'comments_dir={comments_dir}\n')
           PY
 
-      - name: Create PR comment with delta
+      - name: Create PR comment with diffs
         if: steps.detect.outputs.has_baselines == 'true'
         uses: actions/github-script@v9
         env:
-          COMMENT_PATH: ${{ steps.delta.outputs.comment_path }}
+          COMMENTS_DIR: ${{ steps.delta.outputs.comments_dir }}
           PR_NUMBER: ${{ steps.detect.outputs.pr_number }}
         with:
           script: |
             const fs = require('fs');
+            const path = require('path');
             const owner = context.repo.owner;
             const repo = context.repo.repo;
             const issue_number = Number(process.env.PR_NUMBER);
-            const body = fs.readFileSync(process.env.COMMENT_PATH, 'utf8');
-
-            await github.rest.issues.createComment({
-              owner,
-              repo,
-              issue_number,
-              body
-            });
+            const commentsDir = process.env.COMMENTS_DIR;
+
+            const commentFiles = fs.readdirSync(commentsDir)
+              .filter(file => file.endsWith('.md'))
+              .sort((a, b) => a.localeCompare(b));
+
+            for (const file of commentFiles) {
+              const body = fs.readFileSync(path.join(commentsDir, file), 'utf8');
+              await github.rest.issues.createComment({
+                owner,
+                repo,
+                issue_number,
+                body
+              });
+            }
 
-            console.log(`Created new API review comment for PR #${issue_number}.`);
+            console.log(`Created ${commentFiles.length} API review comment(s) for PR #${issue_number}.`);