[Preview link generator] Add file annotation functionality

actions/preview-link-generator/README.md

@@ -9,10 +9,16 @@ on: [pull_request_target]
 
 jobs:
   preview_link_generator_job:
+    permissions:
+      checks: write
+      pull-requests: write
     runs-on: ubuntu-latest
     steps:
     - uses: dotnet/docs-tools/actions/preview-link-generator@main
       with:
         repo_token: ${{ secrets.GITHUB_TOKEN }}
         max_wait_time_minutes: 20
+        annotate_file_warnings: true
 ```
+
+When `annotate_file_warnings` is enabled, the action creates check-run annotations for build errors and warnings that occur on added lines in the pull request. Diagnostics on unchanged lines are ignored. The workflow token requires `checks: write` for this option.

actions/preview-link-generator/__tests__/pull-updater.test.ts

@@ -1,12 +1,15 @@
 import { exportedForTesting } from "../src/pull-updater";
-import { describe, expect, it } from "@jest/globals";
+import { beforeAll, describe, expect, it } from "@jest/globals";
 import { WorkflowInput, workflowInput } from "../src/types/WorkflowInput";
 
 const {
     appendTable,
     buildMarkdownPreviewTableFromExtractedLinks,
     calculateMaxPollAttempts,
+    extractChangedLinesFromPatch,
+    extractDiagnosticsFromBuildReport,
     extractPreviewLinksFromBuildReport,
+    filterDiagnosticsToChangedLines,
     PREVIEW_TABLE_END,
     PREVIEW_TABLE_START,
     replaceExistingTable,
@@ -82,6 +85,7 @@ ${PREVIEW_TABLE_END}`;
         setInput("COLLAPSIBLE_AFTER", "7");
         setInput("MAX_ROW_COUNT", "42");
         setInput("MAX_WAIT_TIME_MINUTES", "15");
+        setInput("annotate_file_warnings", "true");
         setInput("REPO_TOKEN", "test-token");
 
         const opts: WorkflowInput = workflowInput;
@@ -90,6 +94,7 @@ ${PREVIEW_TABLE_END}`;
         expect(opts.collapsibleAfter).toBe(7);
         expect(opts.maxRowCount).toBe(42);
         expect(opts.maxWaitTimeMinutes).toBe(15);
+        expect(opts.annotateFiles).toBe(true);
         expect(opts.repoToken).toBe("test-token");
     });
 
@@ -130,6 +135,94 @@ ${PREVIEW_TABLE_END}`;
         );
     });
 
+    it("extracts errors and warnings from validated file details", () => {
+        const html = `
+<table>
+    <tr>
+        <td>File</td><td>Status</td><td>Preview URL</td><td>Details</td>
+    </tr>
+    <tr>
+        <td>articles/create.md</td><td>Warning</td><td>View</td>
+        <td>
+            Line 61: [Warning] Multiple H1s are not allowed.<br />
+            Line 83: [Error] Another top-level heading was found.
+        </td>
+    </tr>
+    <tr>
+        <td>articles/overview.md</td><td>Warning</td><td>View</td>
+        <td>Line 92: [Warning] Duplicate heading: 'Next step'.</td>
+    </tr>
+</table>`;
+
+        const diagnostics = extractDiagnosticsFromBuildReport(html);
+
+        expect(diagnostics).toEqual([
+            {
+                path: "articles/create.md",
+                line: 61,
+                severity: "Warning",
+                message: "Multiple H1s are not allowed.",
+            },
+            {
+                path: "articles/create.md",
+                line: 83,
+                severity: "Error",
+                message: "Another top-level heading was found.",
+            },
+            {
+                path: "articles/overview.md",
+                line: 92,
+                severity: "Warning",
+                message: "Duplicate heading: 'Next step'.",
+            },
+        ]);
+    });
+
+    it("filters diagnostics to added lines in the PR patch", () => {
+        const createChangedLines =
+            extractChangedLinesFromPatch(`@@ -60,2 +60,3 @@
+ unchanged line
++new line 61
+ unchanged line`);
+        const overviewChangedLines =
+            extractChangedLinesFromPatch(`@@ -91,1 +91,2 @@
+ unchanged line
++new line 92`);
+        const diagnostics = [
+            {
+                path: "articles/create.md",
+                line: 61,
+                severity: "Warning" as const,
+                message: "Changed warning",
+            },
+            {
+                path: "articles/create.md",
+                line: 83,
+                severity: "Warning" as const,
+                message: "Unchanged warning",
+            },
+            {
+                path: "articles/overview.md",
+                line: 92,
+                severity: "Error" as const,
+                message: "Changed error",
+            },
+        ];
+
+        const filtered = filterDiagnosticsToChangedLines(
+            diagnostics,
+            new Map([
+                ["articles/create.md", createChangedLines],
+                ["articles/overview.md", overviewChangedLines],
+            ])
+        );
+
+        expect(filtered.map(({ path, line }) => `${path}:${line}`)).toEqual([
+            "articles/create.md:61",
+            "articles/overview.md:92",
+        ]);
+    });
+
     it("buildMarkdownPreviewTableFromExtractedLinks creates table from build report links", () => {
         setInput("COLLAPSIBLE_AFTER", "10");
         const links = new Map<string, string>([
@@ -153,8 +246,8 @@ ${PREVIEW_TABLE_END}`;
             "#### Internal previews\n\n" +
                 "| File | Preview link |\n" +
                 "|:--|:--|\n" +
-                "| [docs/a.md](https://github.com/dotnet/docs/blob/oid/docs/a.md) | [Preview published page](https://review.learn.microsoft.com/en-us/dotnet/a?branch=pr-en-us-7) |\n" +
-                "| [docs/b.yml](https://github.com/dotnet/docs/blob/oid/docs/b.yml) | [Preview published page](https://review.learn.microsoft.com/en-us/dotnet/b?branch=pr-en-us-7) |\n"
+                "| [docs/a.md](https://github.com/dotnet/docs/blob/oid/docs/a.md) | [Learn preview](https://review.learn.microsoft.com/en-us/dotnet/a?branch=pr-en-us-7) |\n" +
+                "| [docs/b.yml](https://github.com/dotnet/docs/blob/oid/docs/b.yml) | [Learn preview](https://review.learn.microsoft.com/en-us/dotnet/b?branch=pr-en-us-7) |\n"
         );
     });
 
@@ -171,7 +264,9 @@ ${PREVIEW_TABLE_END}`;
             "https://github.com/dotnet/docs/pull/7/checks"
         );
 
-        expect(actual).toContain("<details><summary><strong>Toggle expand/collapse</strong></summary><br/>");
+        expect(actual).toContain(
+            "<details><summary><strong>Toggle expand/collapse</strong></summary><br/>"
+        );
         expect(actual).toContain("</details>");
     });
 });

actions/preview-link-generator/action.yml

@@ -3,17 +3,20 @@ description: 'Waits for OpenPublishing.Build to complete, then extracts preview
 author: 'Genevieve Warren'
 inputs:
   repo_token:
-    description: 'The GITHUB_TOKEN secret. Requires the following permissions: pull-requests: write.'
+    description: 'The GITHUB_TOKEN secret. Requires pull-requests: write and, when annotate_file_warnings is true, checks: write.'
     required: true
   collapsible_after:
     description: 'The number at which the automated preview table defaults as collapsed but expandable, using the HTML summary and details elements.'
-    default: '10'
+    default: '12'
   max_row_count:
     description: 'The maximum number of rows to display in the automated preview table.'
-    default: '30'
+    default: '50'
   max_wait_time_minutes:
     description: 'The maximum number of minutes to wait for the OpenPublishing.Build status check to complete.'
     default: '20'
+  annotate_file_warnings:
+    description: 'Whether to annotate changed lines on the Files changed tab with errors and warnings from the build report.'
+    default: 'false'
 runs:
   using: 'node16'
   main: 'dist/index.js'