[automated] Merge branch 'release/10.0' => 'main'

.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

@@ -1,34 +1,54 @@
-# This workflow labels merged PRs that modify `*.baseline.json` files with `api-review`,
-# computes ApiChief deltas between the original and merged baseline files, and posts the
-# results back to the pull request as a review comment.
+# This workflow labels PRs that modify `*.baseline.json` files with `api-review`,
+# computes ApiChief deltas between the base and selected PR baseline files, and posts the
+# results back to the pull request as a comment.
 
-name: Comment API baseline deltas on merged PRs
+name: Comment API baseline deltas on PRs
 
 on:
   pull_request_target:
     types: [closed]
     branches:
       - main
       - release/**
+  workflow_dispatch:
+    inputs:
+      pr-number:
+        description: Pull request number to process
+        required: true
+        type: number
 
 permissions:
   contents: read
   issues: write
-  pull-requests: read
+  pull-requests: write
 
 jobs:
   api-review:
-    if: github.event.pull_request.merged == true
+    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.merged == true
     runs-on: ubuntu-latest
     steps:
       - name: Detect changed baseline files and add label
         id: detect
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const owner = context.repo.owner;
             const repo = context.repo.repo;
-            const prNumber = context.payload.pull_request.number;
+            const prNumberInput = context.eventName === 'workflow_dispatch'
+              ? context.payload.inputs?.['pr-number']
+              : context.payload.pull_request.number;
+            const prNumber = Number(prNumberInput);
+
+            if (!Number.isInteger(prNumber) || prNumber <= 0) {
+              core.setFailed(`Invalid PR number: ${prNumber}`);
+              return;
+            }
+
+            const { data: pullRequest } = await github.rest.pulls.get({
+              owner,
+              repo,
+              pull_number: prNumber
+            });
 
             const files = await github.paginate(github.rest.pulls.listFiles, {
               owner,
@@ -45,11 +65,18 @@ jobs:
                 previous_filename: file.previous_filename ?? null
               }));
 
+            core.setOutput('pr_number', String(prNumber));
+            core.setOutput('base_sha', pullRequest.base.sha);
+            core.setOutput('target_sha', pullRequest.merge_commit_sha ?? pullRequest.head.sha);
             core.setOutput('has_baselines', String(baselineFiles.length > 0));
             core.setOutput('files_json', JSON.stringify(baselineFiles));
 
+            if (!pullRequest.merged) {
+              console.log(`PR #${prNumber} is not merged; using head SHA ${pullRequest.head.sha}.`);
+            }
+
             if (baselineFiles.length === 0) {
-              console.log('No changed baseline files detected on this merged PR.');
+              console.log(`No changed baseline files detected on PR #${prNumber}.`);
               return;
             }
 
@@ -60,30 +87,30 @@ jobs:
               labels: ['api-review']
             });
 
-            console.log(`Detected ${baselineFiles.length} changed baseline file(s).`);
+            console.log(`Detected ${baselineFiles.length} changed baseline file(s) on PR #${prNumber}.`);
 
-      - name: Check out merged commit
+      - name: Check out selected commit
         if: steps.detect.outputs.has_baselines == 'true'
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
-          ref: ${{ github.event.pull_request.merge_commit_sha }}
+          ref: ${{ steps.detect.outputs.target_sha }}
           fetch-depth: 1
 
       - name: Restore repo-local .NET SDK
         if: steps.detect.outputs.has_baselines == 'true'
         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
         env:
           FILES_JSON: ${{ steps.detect.outputs.files_json }}
           OWNER: ${{ github.repository_owner }}
           REPO: ${{ github.event.repository.name }}
-          BASE_SHA: ${{ github.event.pull_request.base.sha }}
-          MERGE_SHA: ${{ github.event.pull_request.merge_commit_sha }}
+          BASE_SHA: ${{ steps.detect.outputs.base_sha }}
+          TARGET_SHA: ${{ steps.detect.outputs.target_sha }}
         run: |
           set -euo pipefail
 
@@ -110,7 +137,7 @@ jobs:
           owner = os.environ['OWNER']
           repo = os.environ['REPO']
           base_sha = os.environ['BASE_SHA']
-          merge_sha = os.environ['MERGE_SHA']
+          target_sha = os.environ['TARGET_SHA']
           dotnet = os.environ['DOTNET']
           apichief = os.environ['APICHIEF_PATH']
           workdir = pathlib.Path(os.environ['WORKDIR'])
@@ -130,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 = ''
+
+          def append_section(section: str) -> None:
+              nonlocal current_body
 
-          sections: list[str] = []
+              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(merge_sha, filename, new_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)
@@ -158,73 +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 merged 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 merged 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-delta-comment -->\n'
-              '## API review baseline changes\n\n'
-              'This merged PR modified one or more `*.baseline.json` files. '
-              'The deltas below were generated by `ApiChief` between the pre-merge and merged 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: Upsert PR comment with delta
+      - name: Create PR comment with diffs
         if: steps.detect.outputs.has_baselines == 'true'
-        uses: actions/github-script@v8
+        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 = context.payload.pull_request.number;
-            const marker = '<!-- api-review-delta-comment -->';
-            const body = fs.readFileSync(process.env.COMMENT_PATH, 'utf8');
+            const issue_number = Number(process.env.PR_NUMBER);
+            const commentsDir = process.env.COMMENTS_DIR;
 
-            const comments = await github.paginate(github.rest.issues.listComments, {
-              owner,
-              repo,
-              issue_number,
-              per_page: 100
-            });
+            const commentFiles = fs.readdirSync(commentsDir)
+              .filter(file => file.endsWith('.md'))
+              .sort((a, b) => a.localeCompare(b));
 
-            const existing = comments.find(comment => comment.body?.includes(marker));
-
-            if (existing) {
-              await github.rest.issues.updateComment({
-                owner,
-                repo,
-                comment_id: existing.id,
-                body
-              });
-              console.log(`Updated existing API review comment (${existing.id}).`);
-            } else {
+            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.');
             }
+
+            console.log(`Created ${commentFiles.length} API review comment(s) for PR #${issue_number}.`);

.github/workflows/issues-closed.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-slim
     steps:
       - name: Reclose as not planned if external user
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const issue = context.payload.issue;

.github/workflows/label-and-milestone-issues.yml

@@ -22,7 +22,7 @@ jobs:
     runs-on: ubuntu-slim
     steps:
       - name: Label issues and update milestones
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const owner = context.repo.owner;

.github/workflows/validate-pr-target-branch.yml

@@ -19,7 +19,7 @@ jobs:
     runs-on: ubuntu-slim
     steps:
       - name: Check PR target branch and author permissions
-        uses: actions/github-script@v8
+        uses: actions/github-script@v9
         with:
           script: |
             const pr = context.payload.pull_request;

.gitignore

@@ -218,6 +218,9 @@ _pkginfo.txt
 # but keep track of directories ending in .cache
 !*.[Cc]ache/
 
+# VS Code cache files
+*.lscache
+
 # Others
 ClientBin/
 ~$*