ci: detect breaking-change commits in PRs

Adds a workflow that scans every commit in a pull request for
Conventional Commits breaking-change markers (`type!:` or
`BREAKING CHANGE:` footer) limited to the packages tracked by
.release-it.json (appkit, appkit-ui, shared).

When a breaking commit is found, the job posts a sticky PR comment
explaining the major-version impact and fails the check, unless the
PR carries an `allow-breaking-change` label. This prevents accidental
major bumps from landing on main once the new check is added to
branch-protection required checks.

Signed-off-by: MarioCadenas <MarioCadenas@users.noreply.github.com>

Author: MarioCadenas

.github/scripts/detect-breaking-commits.sh

@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+#
+# Scans commits between $BASE_SHA and $HEAD_SHA for Conventional Commits
+# breaking-change markers, restricted to the packages tracked by
+# .release-it.json. Writes `found` and (on match) `list` to $GITHUB_OUTPUT.
+#
+# Required env: BASE_SHA, HEAD_SHA, GITHUB_OUTPUT
+
+set -euo pipefail
+
+PATHS=(packages/appkit packages/appkit-ui packages/shared)
+
+# Conventional Commits breaking-change markers:
+#   1. `type!:` or `type(scope)!:` in the subject line
+#   2. `BREAKING CHANGE:` or `BREAKING-CHANGE:` footer line
+PATTERN='^(feat|fix|chore|refactor|perf|build|ci|docs|style|test|revert)(\([^)]+\))?!:|^BREAKING[ -]CHANGE:'
+
+breaking=""
+while IFS= read -r sha; do
+  [ -z "$sha" ] && continue
+  msg=$(git log -1 --format=%B "$sha")
+  if printf '%s\n' "$msg" | grep -Eq "$PATTERN"; then
+    subject=$(git log -1 --format=%s "$sha")
+    breaking+="- \`${sha:0:7}\` ${subject}"$'\n'
+  fi
+done < <(git rev-list "$BASE_SHA".."$HEAD_SHA" -- "${PATHS[@]}")
+
+if [ -n "$breaking" ]; then
+  {
+    echo "found=true"
+    echo "list<<COMMITS_EOF"
+    printf '%s' "$breaking"
+    echo "COMMITS_EOF"
+  } >> "$GITHUB_OUTPUT"
+  echo "Breaking commits found:"
+  printf '%s' "$breaking"
+else
+  echo "found=false" >> "$GITHUB_OUTPUT"
+  echo "No breaking commits found."
+fi

.github/scripts/upsert-breaking-change-comment.cjs

@@ -0,0 +1,71 @@
+/**
+ * Upserts (or removes) a sticky PR comment summarizing breaking commits
+ * detected by `detect-breaking-commits.sh`.
+ *
+ * Invoked via `actions/github-script`. Inputs come from environment vars:
+ *   FOUND          - "true" if the scan found breaking commits
+ *   BREAKING_LIST  - markdown bullet list of breaking commits
+ *   ALLOWED        - "true" if the PR carries the allow-breaking-change label
+ */
+
+const MARKER = "<!-- pr-breaking-change-check -->";
+
+module.exports = async ({ github, context }) => {
+  const { owner, repo } = context.repo;
+  const issue_number = context.issue.number;
+  const found = process.env.FOUND === "true";
+  const allowed = process.env.ALLOWED === "true";
+  const list = process.env.BREAKING_LIST || "";
+
+  const comments = await github.paginate(github.rest.issues.listComments, {
+    owner,
+    repo,
+    issue_number,
+    per_page: 100,
+  });
+  const existing = comments.find((c) => c.body?.includes(MARKER));
+
+  if (!found) {
+    if (existing) {
+      await github.rest.issues.deleteComment({
+        owner,
+        repo,
+        comment_id: existing.id,
+      });
+    }
+    return;
+  }
+
+  const status = allowed
+    ? "> This PR has the `allow-breaking-change` label, so this check will pass. Make sure the next release is intentionally bumped to a major version."
+    : "> Add the **`allow-breaking-change`** label to this PR if the breaking change is intentional, or rewrite the offending commits to remove the `!` / `BREAKING CHANGE:` footer.";
+
+  const body = [
+    MARKER,
+    "### Breaking change detected",
+    "",
+    "The following commits in this PR contain Conventional Commits breaking-change markers (`type!:` or `BREAKING CHANGE:` footer) and touch packages tracked by `.release-it.json`:",
+    "",
+    list.trim(),
+    "",
+    "Merging this PR will force a **major** version bump on the next release (`bumpStrict: true` in `.release-it.json`).",
+    "",
+    status,
+  ].join("\n");
+
+  if (existing) {
+    await github.rest.issues.updateComment({
+      owner,
+      repo,
+      comment_id: existing.id,
+      body,
+    });
+  } else {
+    await github.rest.issues.createComment({
+      owner,
+      repo,
+      issue_number,
+      body,
+    });
+  }
+};

.github/workflows/pr-breaking-change.yml

@@ -0,0 +1,51 @@
+name: PR Breaking Change Check
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, labeled, unlabeled]
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  detect-breaking:
+    name: Detect Breaking Commits
+    runs-on:
+      group: databricks-protected-runner-group
+      labels: linux-ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Find breaking commits
+        id: scan
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: bash .github/scripts/detect-breaking-commits.sh
+
+      - name: Upsert sticky PR comment
+        uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1
+        env:
+          FOUND: ${{ steps.scan.outputs.found }}
+          BREAKING_LIST: ${{ steps.scan.outputs.list }}
+          ALLOWED: ${{ contains(github.event.pull_request.labels.*.name, 'allow-breaking-change') }}
+        with:
+          script: |
+            const upsert = require('./.github/scripts/upsert-breaking-change-comment.cjs');
+            await upsert({ github, context });
+
+      - name: Fail unless explicitly allowed
+        if: steps.scan.outputs.found == 'true' && !contains(github.event.pull_request.labels.*.name, 'allow-breaking-change')
+        run: |
+          echo "::error::Breaking-change commits detected in tracked packages. Add the 'allow-breaking-change' label to bypass, or rewrite the offending commits."
+          exit 1

knip.json

@@ -23,7 +23,8 @@
     "packages/appkit/src/plugins/agents/load-agents.ts",
     "template/**",
     "tools/**",
-    "docs/**"
+    "docs/**",
+    ".github/scripts/**"
   ],
   "ignoreDependencies": ["json-schema-to-typescript"],
   "ignoreBinaries": ["tarball"]