feat: adds custom comment markers (#647)

* feat: implement custom comment markers

Fixes #646

* chore: add permission comment

* chore: add more marker tests

Author: Marsup

README.md

@@ -140,6 +140,34 @@ If your project includes multiple test suites and you want to consolidate their
         json-final-path: './coverage/coverage-final-backend.json'
 ```
 
+#### Injecting into the Pull Request Description
+
+Instead of posting a separate comment, the action can inject the report into a section of the **pull request description**, handy when you use a PR template and want coverage to live in a specific place. Add a start/end marker pair to your PR template, and the action will replace everything between them on every run, leaving the rest of the description untouched:
+
+```md
+## Coverage
+
+<!-- vitest-coverage-report-marker-start-root -->
+<!-- vitest-coverage-report-marker-end-root -->
+```
+
+The `root` suffix is the same postfix used for the comment marker: it defaults to `root`, but becomes the [`name`](#name) if you set one (or the `working-directory` otherwise). So a step with `name: 'Frontend'` looks for `...-marker-start-Frontend`/`...-marker-end-Frontend`, which lets you inject several reports into one description:
+
+```md
+<!-- vitest-coverage-report-marker-start-Frontend -->
+<!-- vitest-coverage-report-marker-end-Frontend -->
+
+<!-- vitest-coverage-report-marker-start-Backend -->
+<!-- vitest-coverage-report-marker-end-Backend -->
+```
+
+Notes:
+
+- Rewriting the description needs the same [`pull-requests: write`](#required-permissions) permission as commenting, so there's nothing extra to grant, but a read-only token can't update it and the run will fail.
+- When the markers are present, the report goes into the description **only**, no comment is posted. If you previously ran in comment mode, delete the old comment once by hand.
+- Only one marker of a pair (or an end before its start) is treated as a mistake: the action logs a warning and falls back to posting a comment.
+- Because every run rewrites the same description, parallel jobs writing **different** markers into it can clobber each other (last write wins). If you inject multiple reports into one description, run them in a single job or guard them with a [`concurrency`](https://docs.github.com/en/actions/using-jobs/using-concurrency) group.
+
 #### Threshold Icons
 
 If you haven't established strict coverage thresholds in your `vitest.config` (which would fail the test run), you can still use the `threshold-icons` option to control the status icons displayed in the PR comment based on coverage percentage.

src/index.ts

@@ -13,6 +13,7 @@ import { generateCommitSHAUrl } from "./report/generateCommitSHAUrl.js";
 import { generateFileCoverageHtml } from "./report/generateFileCoverageHtml.js";
 import { generateHeadline } from "./report/generateHeadline.js";
 import { generateSummaryTableHtml } from "./report/generateSummaryTableHtml.js";
+import { getWorkflowSummaryURL } from "./report/getWorkflowSummaryURL.js";
 import type { JsonSummary } from "./types/JsonSummary.js";
 import { writeSummaryToCommit } from "./writeSummaryToComment.js";
 import { writeSummaryToPR } from "./writeSummaryToPR.js";
@@ -168,12 +169,6 @@ function getMarkerPostfix({
 	return "root";
 }
 
-function getWorkflowSummaryURL() {
-	const { owner, repo } = github.context.repo;
-	const { runId } = github.context;
-	return `${github.context.serverUrl}/${owner}/${repo}/actions/runs/${runId}`;
-}
-
 run()
 	.then(() => {
 		core.info("Report generated successfully.");

src/report/getWorkflowSummaryURL.ts

@@ -0,0 +1,9 @@
+import * as github from "@actions/github";
+
+function getWorkflowSummaryURL() {
+	const { owner, repo } = github.context.repo;
+	const { runId } = github.context;
+	return `${github.context.serverUrl}/${owner}/${repo}/actions/runs/${runId}`;
+}
+
+export { getWorkflowSummaryURL };

src/writeSummaryToPR.test.ts

@@ -11,6 +11,8 @@ const mockContext = vi.hoisted(() => ({
 		repo: "repo",
 	},
 	payload: {},
+	serverUrl: "https://github.com",
+	runId: 42,
 }));
 vi.mock("@actions/github", () => ({
 	context: mockContext,
@@ -41,6 +43,10 @@ describe("writeSummaryToPR()", () => {
 					updateComment: vi.fn(),
 					createComment: vi.fn(),
 				},
+				pulls: {
+					get: vi.fn().mockResolvedValue({ data: { body: "" } }),
+					update: vi.fn(),
+				},
 			},
 		} as unknown as Octokit;
 
@@ -97,4 +103,82 @@ describe("writeSummaryToPR()", () => {
 		});
 		expect(mockOctokit.rest.issues.updateComment).not.toHaveBeenCalled();
 	});
+
+	it("injects into the PR body between markers and posts no comment", async () => {
+		mockOctokit.rest.pulls.get = vi.fn().mockResolvedValue({
+			data: {
+				body: "## Intro\ntext\n<!-- vitest-coverage-report-marker-start-root -->\nold\n<!-- vitest-coverage-report-marker-end-root -->\n## Outro",
+			},
+		});
+
+		await writeSummaryToPR({
+			octokit: mockOctokit,
+			summary: mockSummary,
+			prNumber: 123,
+		});
+
+		expect(mockOctokit.rest.pulls.update).toHaveBeenCalledWith({
+			owner: "owner",
+			repo: "repo",
+			pull_number: 123,
+			body: "## Intro\ntext\n<!-- vitest-coverage-report-marker-start-root -->\nsummary content\n<!-- vitest-coverage-report-marker-end-root -->\n## Outro",
+		});
+		expect(mockOctokit.rest.issues.createComment).not.toHaveBeenCalled();
+		expect(mockOctokit.rest.issues.updateComment).not.toHaveBeenCalled();
+	});
+
+	it("warns and falls back to a comment when only one marker is present", async () => {
+		mockOctokit.rest.pulls.get = vi.fn().mockResolvedValue({
+			data: {
+				body: "text\n<!-- vitest-coverage-report-marker-start-root -->\nno end marker",
+			},
+		});
+
+		await writeSummaryToPR({
+			octokit: mockOctokit,
+			summary: mockSummary,
+			prNumber: 123,
+		});
+
+		expect(core.warning).toHaveBeenCalled();
+		expect(mockOctokit.rest.pulls.update).not.toHaveBeenCalled();
+		expect(mockOctokit.rest.issues.updateComment).toHaveBeenCalled();
+	});
+
+	it("warns and falls back to a comment when the end marker comes first", async () => {
+		mockOctokit.rest.pulls.get = vi.fn().mockResolvedValue({
+			data: {
+				body: "text\n<!-- vitest-coverage-report-marker-end-root -->\nreversed\n<!-- vitest-coverage-report-marker-start-root -->",
+			},
+		});
+
+		await writeSummaryToPR({
+			octokit: mockOctokit,
+			summary: mockSummary,
+			prNumber: 123,
+		});
+
+		expect(core.warning).toHaveBeenCalled();
+		expect(mockOctokit.rest.pulls.update).not.toHaveBeenCalled();
+		expect(mockOctokit.rest.issues.updateComment).toHaveBeenCalled();
+	});
+
+	it("replaces an oversized report with a stub linking to the workflow summary", async () => {
+		mockSummary.stringify = vi.fn().mockReturnValue("x".repeat(70000));
+		mockOctokit.paginate.iterator = vi.fn().mockReturnValue([{ data: [] }]);
+
+		await writeSummaryToPR({
+			octokit: mockOctokit,
+			summary: mockSummary,
+			prNumber: 123,
+		});
+
+		const body = (
+			mockOctokit.rest.issues.createComment as ReturnType<typeof vi.fn>
+		).mock.calls[0][0].body;
+		expect(body).toContain("too large to inline");
+		expect(body).toContain("https://github.com/owner/repo/actions/runs/42");
+		expect(body).toContain("<!-- vitest-coverage-report-marker-root -->");
+		expect(body.length).toBeLessThanOrEqual(65536);
+	});
 });

src/writeSummaryToPR.ts

@@ -1,9 +1,21 @@
 import * as core from "@actions/core";
 import * as github from "@actions/github";
 import type { Octokit } from "./octokit";
+import { getWorkflowSummaryURL } from "./report/getWorkflowSummaryURL.js";
+
+// GitHub caps issue/PR bodies and comments at 65536 characters.
+const MAX_BODY_LENGTH = 65536;
 
 const COMMENT_MARKER = (markerPostfix = "root") =>
 	`<!-- vitest-coverage-report-marker-${markerPostfix} -->`;
+const START_MARKER_PREFIX = "<!-- vitest-coverage-report-marker-start-";
+const START_MARKER = (markerPostfix = "root") =>
+	`${START_MARKER_PREFIX}${markerPostfix} -->`;
+const END_MARKER = (markerPostfix = "root") =>
+	`<!-- vitest-coverage-report-marker-end-${markerPostfix} -->`;
+
+const oversizeStub = () =>
+	`⚠️ Coverage report too large to inline, see the [workflow summary](${getWorkflowSummaryURL()}).`;
 
 const writeSummaryToPR = async ({
 	octokit,
@@ -22,12 +34,18 @@ const writeSummaryToPR = async ({
 		return;
 	}
 
-	const commentBody = `${summary.stringify()}\n\n${COMMENT_MARKER(markerPostfix)}`;
-	const existingComment = await findCommentByBody(
-		octokit,
-		COMMENT_MARKER(markerPostfix),
-		prNumber,
-	);
+	const report = summary.stringify();
+
+	// If the PR body carries our marker pair, inject there and post no comment.
+	if (await tryInjectIntoBody({ octokit, report, markerPostfix, prNumber })) {
+		return;
+	}
+
+	const marker = COMMENT_MARKER(markerPostfix);
+	const full = `${report}\n\n${marker}`;
+	const commentBody =
+		full.length <= MAX_BODY_LENGTH ? full : `${oversizeStub()}\n\n${marker}`;
+	const existingComment = await findCommentByBody(octokit, marker, prNumber);
 
 	if (existingComment) {
 		await octokit.rest.issues.updateComment({
@@ -46,6 +64,81 @@ const writeSummaryToPR = async ({
 	}
 };
 
+// Returns true when the report was injected into the PR body between the
+// start/end markers. Returns false (so the caller posts a comment) when the
+// markers are absent, or emits a warning and returns false when they are
+// malformed (only one present, or end before start).
+async function tryInjectIntoBody({
+	octokit,
+	report,
+	markerPostfix,
+	prNumber,
+}: {
+	octokit: Octokit;
+	report: string;
+	markerPostfix?: string;
+	prNumber: number;
+}): Promise<boolean> {
+	const { data: pullRequest } = await octokit.rest.pulls.get({
+		owner: github.context.repo.owner,
+		repo: github.context.repo.repo,
+		pull_number: prNumber,
+	});
+
+	const body = pullRequest.body ?? "";
+	const start = START_MARKER(markerPostfix);
+	const end = END_MARKER(markerPostfix);
+	const startIdx = body.indexOf(start);
+	const endIdx = body.indexOf(end);
+
+	if (startIdx === -1 && endIdx === -1) {
+		return false;
+	}
+
+	if (startIdx === -1 || endIdx === -1 || endIdx < startIdx + start.length) {
+		core.warning(
+			`Found incomplete coverage markers in the pull request body. Expected both "${start}" and "${end}" with the start before the end. Falling back to a comment.`,
+		);
+		return false;
+	}
+
+	const before = body.slice(0, startIdx + start.length);
+	const after = body.slice(endIdx);
+	const stub = oversizeStub();
+
+	// Reserve one stub's worth of room per other marker region so sibling runs
+	// can still write their own region into the shared body. Empty regions are
+	// the ones that still need to grow. The +2 accounts for the newlines that
+	// wrap each injected region.
+	const otherRegions = Math.max(0, countStartMarkers(body) - 1);
+	const margin = otherRegions * (stub.length + 2);
+
+	const withReport = `${before}\n${report}\n${after}`;
+	const newBody =
+		withReport.length <= MAX_BODY_LENGTH - margin
+			? withReport
+			: `${before}\n${stub}\n${after}`;
+
+	await octokit.rest.pulls.update({
+		owner: github.context.repo.owner,
+		repo: github.context.repo.repo,
+		pull_number: prNumber,
+		body: newBody,
+	});
+
+	return true;
+}
+
+function countStartMarkers(body: string): number {
+	let count = 0;
+	let idx = body.indexOf(START_MARKER_PREFIX);
+	while (idx !== -1) {
+		count++;
+		idx = body.indexOf(START_MARKER_PREFIX, idx + START_MARKER_PREFIX.length);
+	}
+	return count;
+}
+
 async function findCommentByBody(
 	octokit: Octokit,
 	commentBodyIncludes: string,