ci(danger): PR-template section check

Author: alandefreitas

util/danger/README.md

@@ -36,7 +36,7 @@ npm --prefix util/danger run danger:ci     # run Danger in CI mode (requires Git
 - Aggregate PR source churn triggers a warning above 5000 lines (much more generous than the per-commit limit, since well-sliced commits can still amount to a large overall change).
 - PR description length is checked against a log-scaled floor (`80 * log2(churn)` characters). Tiny diffs need ~80 chars; ~1k-line changes need ~800; ~30k-line changes need ~1200. HTML comments in the body (e.g. PR template scaffolding) are stripped before measurement.
 - Feature PRs (`feat:` commits, `feat` PR title, or `feature` label) without any `docs/` change get a light warning. Opt out with the `no-docs-needed` label or a `[skip danger docs]` marker in the PR body.
-- The PR template (`.github/pull_request_template.md`) mirrors these rules; following it tends to satisfy all of them automatically.
+- The PR template (`.github/pull_request_template.md`) mirrors these rules; following it tends to satisfy all of them automatically. Section headers from the template (any level) that are missing from the PR body are reported as an informational note rather than a warning.
 
 ## Updating rules
 

util/danger/fixtures/sample-pr.json

@@ -32,5 +32,6 @@
   ],
   "prBody": "Sample rationale\\n\\nTesting: unit tests locally",
   "prTitle": "Sample Danger fixture",
-  "labels": []
+  "labels": [],
+  "prTemplate": "_What this PR does and why._\n\n## Changes\n\n_Replace the lines that apply._\n\n## Testing\n\n_How this change stays tested._\n\n## Documentation\n\n_What was updated._\n"
 }

util/danger/logic.test.ts

@@ -14,13 +14,33 @@ import {
     evaluateDanger,
     expectedBodyLength,
     parseCommitSummary,
+    parsePrTemplateSections,
+    prTemplateInfos,
     basicChecks,
     summarizeScopes,
     validateCommits,
     type CommitInfo,
     type DangerInputs,
 } from "./logic";
 
+const sampleTemplate = [
+    "<!-- Fill this in yourself. -->",
+    "",
+    "_What this PR does and why._",
+    "",
+    "## Changes",
+    "",
+    "_Replace the lines that apply._",
+    "",
+    "## Testing",
+    "",
+    "_How this change stays tested._",
+    "",
+    "## Documentation",
+    "",
+    "_What was updated._",
+].join("\n");
+
 describe("parseCommitSummary", () => {
     // Ensures we correctly extract type, scope, and subject when format is valid.
     it("parses valid commit summaries", () => {
@@ -139,6 +159,123 @@ describe("commitSizeInfos", () => {
     });
 });
 
+describe("parsePrTemplateSections", () => {
+    // Pulls H2 headers in document order; ignores intro paragraphs and comments.
+    it("extracts H2 headers from the template", () => {
+        expect(parsePrTemplateSections(sampleTemplate)).toEqual(["Changes", "Testing", "Documentation"]);
+    });
+
+    // No headers means no sections to enforce.
+    it("returns an empty array when there are no headers", () => {
+        expect(parsePrTemplateSections("just a paragraph\n\nno headers here")).toEqual([]);
+    });
+
+    // Handles any ATX heading level so future templates can mix H1/H2/H3.
+    it("extracts headings of any ATX level", () => {
+        const template = [
+            "# Summary",
+            "## Changes",
+            "### Subsection",
+            "#### Detail",
+            "##### Deeper",
+            "###### Deepest",
+        ].join("\n");
+        expect(parsePrTemplateSections(template)).toEqual([
+            "Summary",
+            "Changes",
+            "Subsection",
+            "Detail",
+            "Deeper",
+            "Deepest",
+        ]);
+    });
+
+    // Strips the optional ATX closing run of `#` characters.
+    it("strips trailing closing hashes from ATX headers", () => {
+        expect(parsePrTemplateSections("## Changes ##\n### Testing ###")).toEqual(["Changes", "Testing"]);
+    });
+
+    // Dedupes by title (case-insensitive) so cross-level repeats don't double-flag.
+    it("dedupes repeated titles across levels", () => {
+        const template = ["## Notes", "### notes", "#### NOTES"].join("\n");
+        expect(parsePrTemplateSections(template)).toEqual(["Notes"]);
+    });
+});
+
+describe("prTemplateInfos", () => {
+    // A body that includes every template header produces no info.
+    it("stays quiet when all template sections are present", () => {
+        const body = [
+            "Rationale for the change.",
+            "",
+            "## Changes",
+            "- Source: tweak.",
+            "",
+            "## Testing",
+            "Ran the suite.",
+            "",
+            "## Documentation",
+            "No user-facing change.",
+        ].join("\n");
+        expect(prTemplateInfos(body, ["Changes", "Testing", "Documentation"])).toEqual([]);
+    });
+
+    // Missing sections are listed in the single info message.
+    it("lists missing sections", () => {
+        const body = ["Rationale.", "", "## Changes", "- Source: tweak."].join("\n");
+        const infos = prTemplateInfos(body, ["Changes", "Testing", "Documentation"]);
+        expect(infos).toHaveLength(1);
+        expect(infos[0]).toContain("**Testing**");
+        expect(infos[0]).toContain("**Documentation**");
+        expect(infos[0]).not.toContain("**Changes**");
+    });
+
+    // Header matching is case-insensitive so contributors don't trip over capitalization.
+    it("matches headers case-insensitively", () => {
+        const body = ["## changes", "## testing", "## documentation"].join("\n");
+        expect(prTemplateInfos(body, ["Changes", "Testing", "Documentation"])).toEqual([]);
+    });
+
+    // The body can use a different heading level than the template — title alone is what matters.
+    it("matches sections regardless of heading level", () => {
+        const body = ["# Changes", "### Testing", "###### Documentation"].join("\n");
+        expect(prTemplateInfos(body, ["Changes", "Testing", "Documentation"])).toEqual([]);
+    });
+
+    // An empty body is already covered by the empty-description warning — skip to avoid noise.
+    it("skips when the PR body is empty", () => {
+        expect(prTemplateInfos("", ["Changes", "Testing"])).toEqual([]);
+        expect(prTemplateInfos("   \n\n  ", ["Changes", "Testing"])).toEqual([]);
+    });
+
+    // A template with no headers produces no info.
+    it("skips when the template has no headers", () => {
+        expect(prTemplateInfos("some body", [])).toEqual([]);
+    });
+
+    // Singular wording when exactly one section is missing.
+    it("uses singular wording for a single missing section", () => {
+        const body = ["## Changes", "## Testing"].join("\n");
+        const infos = prTemplateInfos(body, ["Changes", "Testing", "Documentation"]);
+        expect(infos[0]).toContain("missing template section:");
+    });
+});
+
+describe("evaluateDanger pr-template info", () => {
+    // The new check is wired into the infos channel so it renders as [!NOTE].
+    it("surfaces missing template sections via infos", () => {
+        const result = evaluateDanger({
+            files: [{ filename: "src/lib/x.cpp", additions: 10, deletions: 1 }],
+            commits: [{ sha: "ab", message: "fix: small change" }],
+            prBody: "A short rationale that explains what is going on, with no template structure at all.",
+            prTitle: "fix: small change",
+            labels: [],
+            prTemplate: sampleTemplate,
+        });
+        expect(result.infos.some((m) => m.includes("missing template sections"))).toBe(true);
+    });
+});
+
 describe("starterChecks", () => {
     // Checks that source changes without accompanying tests produce a warning.
     it("requests tests when source changes without coverage", () => {

util/danger/logic.ts

@@ -98,6 +98,7 @@ export interface DangerInputs {
     prBody: string;
     prTitle: string;
     labels: string[];
+    prTemplate?: string;
 }
 
 /**
@@ -505,6 +506,68 @@ export function commitSizeInfos(commits: CommitInfo[]): string[] {
     return messages;
 }
 
+// Matches any ATX heading (#, ##, …, ######) with optional trailing # marks per the CommonMark spec.
+const atxHeadingPattern = /^[ \t]*#{1,6}[ \t]+(.+?)(?:[ \t]+#+)?[ \t]*$/;
+
+/**
+ * Extract section headers of any level (H1–H6) from a Markdown document.
+ *
+ * Used to discover the section structure of the project's PR template so that
+ * missing sections can be reported back to contributors. Returns titles in
+ * document order, deduped (case-insensitive) so a template that repeats a
+ * heading at different levels does not double-flag.
+ */
+export function parsePrTemplateSections(template: string): string[] {
+    const sections: string[] = [];
+    const seen = new Set<string>();
+    for (const raw of template.split("\n")) {
+        const match = raw.match(atxHeadingPattern);
+        if (!match) continue;
+        const title = match[1].trim();
+        const key = title.toLowerCase();
+        if (!seen.has(key)) {
+            seen.add(key);
+            sections.push(title);
+        }
+    }
+    return sections;
+}
+
+function escapeRegExp(value: string): string {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Report PR-template sections that the body is missing.
+ *
+ * Matches headings of any level (so a body can use `### Testing` even if the
+ * template uses `## Testing`). The template is a convention, not a hard
+ * requirement, so this is an informational note rather than a warning — the
+ * empty-description warning already covers the case where the contributor
+ * wrote nothing at all.
+ */
+export function prTemplateInfos(prBody: string, templateSections: string[]): string[] {
+    if (!prBody.trim() || templateSections.length === 0) {
+        return [];
+    }
+    const missing = templateSections.filter((section) => {
+        const pattern = new RegExp(
+            `^[ \\t]*#{1,6}[ \\t]+${escapeRegExp(section)}(?:[ \\t]+#+)?[ \\t]*$`,
+            "im",
+        );
+        return !pattern.test(prBody);
+    });
+    if (missing.length === 0) {
+        return [];
+    }
+    const noun = missing.length === 1 ? "section" : "sections";
+    const list = missing.map((name) => `**${name}**`).join(", ");
+    return [
+        `PR description is missing template ${noun}: ${list}. ` +
+            "Following the [pull request template](.github/pull_request_template.md) helps reviewers find rationale, testing notes, and docs status quickly.",
+    ];
+}
+
 /**
  * Warn when the aggregate source-scope churn across the whole PR is large.
  *
@@ -687,7 +750,10 @@ export function evaluateDanger(input: DangerInputs): DangerResult {
     const summary = summarizeScopes(input.files);
     const commitValidation = validateCommits(input.commits);
 
-    const infos = commitSizeInfos(input.commits);
+    const infos = [
+        ...commitSizeInfos(input.commits),
+        ...prTemplateInfos(input.prBody || "", parsePrTemplateSections(input.prTemplate || "")),
+    ];
 
     const warnings = [
         ...commitValidation.warnings,

util/danger/runner.ts

@@ -7,10 +7,25 @@
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
 import type { DangerDSLType } from "danger";
 import { evaluateDanger, type CommitInfo, type FileChange } from "./logic";
 import { renderDangerReport } from "./format";
 
+/**
+ * Read the project's PR template so rules can check the body against it.
+ * Missing or unreadable templates degrade gracefully — the template-section
+ * check just stays quiet rather than failing the run.
+ */
+function loadPrTemplate(): string {
+    try {
+        return readFileSync(join(process.cwd(), ".github/pull_request_template.md"), "utf8");
+    } catch {
+        return "";
+    }
+}
+
 // Danger provides these as globals at runtime; we declare them for editors/typecheckers.
 declare const danger: DangerDSLType;
 declare function markdown(message: string, file?: string, line?: number): void;
@@ -113,6 +128,7 @@ export async function runDanger(): Promise<void> {
         prBody: pr.body || "",
         prTitle: pr.title || "",
         labels,
+        prTemplate: loadPrTemplate(),
     });
 
     const warnings = [...fetchWarnings, ...evaluation.warnings];