ci(repo): extend break-check coverage to all SDK packages (#8691)

Author: jacekradko

.changeset/snapi-bump-version.md …set/break-check-coverage-all-packages.md.changeset/snapi-bump-version.md renamed to .changeset/break-check-coverage-all-packages.md .changeset/snapi-bump-version.md renamed to .changeset/break-check-coverage-all-packages.md

@@ -13,13 +13,26 @@ on:
       - release/v4
       - release/core-2
     paths:
+      - 'packages/astro/**'
       - 'packages/backend/**'
+      - 'packages/chrome-extension/**'
       - 'packages/clerk-js/**'
+      - 'packages/expo/**'
+      - 'packages/expo-passkeys/**'
+      - 'packages/express/**'
+      - 'packages/fastify/**'
+      - 'packages/hono/**'
+      - 'packages/localizations/**'
       - 'packages/nextjs/**'
+      - 'packages/nuxt/**'
       - 'packages/react/**'
+      - 'packages/react-router/**'
       - 'packages/shared/**'
+      - 'packages/tanstack-react-start/**'
+      - 'packages/testing/**'
       - 'packages/ui/**'
-      - 'snapi.config.json'
+      - 'packages/vue/**'
+      - 'break-check.config.json'
       - '.github/workflows/api-changes.yml'
 
 permissions:
@@ -30,14 +43,30 @@ concurrency:
   cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 env:
-  SNAPI_PACKAGE: https://pkg.pr.new/clerk/snapi/@clerk/snapi@2479ffce1adb8ff5f1caf95509268774224c121d
-  SNAPI_FILTERS: >-
+  # The tool was renamed snapi -> break-check (package @clerk/break-check, binary
+  # break-check, repo clerk/break-check). Pinned to a pkg.pr.new build of a
+  # specific commit on main.
+  BREAK_CHECK_PACKAGE: https://pkg.pr.new/clerk/break-check/@clerk/break-check@a4db93a68e43e45a71cc958cc4a722d91c5f62b2
+  BREAK_CHECK_FILTERS: >-
+    --filter=@clerk/astro
     --filter=@clerk/backend
+    --filter=@clerk/chrome-extension
     --filter=@clerk/clerk-js
+    --filter=@clerk/expo
+    --filter=@clerk/expo-passkeys
+    --filter=@clerk/express
+    --filter=@clerk/fastify
+    --filter=@clerk/hono
+    --filter=@clerk/localizations
     --filter=@clerk/nextjs
+    --filter=@clerk/nuxt
     --filter=@clerk/react
+    --filter=@clerk/react-router
     --filter=@clerk/shared
+    --filter=@clerk/tanstack-react-start
+    --filter=@clerk/testing
     --filter=@clerk/ui
+    --filter=@clerk/vue
 
 jobs:
   publish-baseline:
@@ -66,18 +95,27 @@ jobs:
           turbo-token: ${{ secrets.TURBO_TOKEN }}
 
       - name: Build declarations
-        run: pnpm turbo build:declarations $TURBO_ARGS $SNAPI_FILTERS
+        run: pnpm turbo build:declarations $TURBO_ARGS $BREAK_CHECK_FILTERS
 
       - name: Generate API snapshot
         run: |
-          pnpm dlx --package "$SNAPI_PACKAGE" snapi snapshot \
+          pnpm dlx --package "$BREAK_CHECK_PACKAGE" break-check snapshot \
             --output "$GITHUB_WORKSPACE/.api-snapshots-baseline"
 
+      - name: Resolve break-check cache key
+        id: break-check-key
+        run: echo "ref=${BREAK_CHECK_PACKAGE##*@}" >> "$GITHUB_OUTPUT"
+
       - name: Save baseline to cache
         uses: actions/cache/save@v4
         with:
           path: .api-snapshots-baseline
-          key: snapi-baseline-${{ github.sha }}
+          # Fold the break-check commit into the key: a snapshot produced by one
+          # break-check version must not be reused by another, since discovery
+          # changes (e.g. wildcard subpath expansion) make the surfaces
+          # incomparable and the diff degenerates into thousands of phantom
+          # additions.
+          key: break-check-baseline-${{ steps.break-check-key.outputs.ref }}-${{ github.sha }}
 
   check-api:
     if: ${{ github.event_name == 'pull_request' && github.event.pull_request.draft == false }}
@@ -96,6 +134,13 @@ jobs:
       - name: Checkout Repo
         uses: actions/checkout@v4
         with:
+          # Pin the "current" side of the diff to the PR head, not the
+          # refs/pull/N/merge ref checkout resolves by default. The merge ref is
+          # the head merged into the moving tip of the base branch, so once main
+          # advances it absorbs unrelated changes and break-check reports them as
+          # this PR's own (clerk/break-check#32). The baseline is already pinned
+          # to base.sha (cache key + worktree fallback below).
+          ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 100
           fetch-tags: false
           filter: 'blob:none'
@@ -109,15 +154,22 @@ jobs:
           turbo-team: ${{ vars.TURBO_TEAM }}
           turbo-token: ${{ secrets.TURBO_TOKEN }}
 
+      - name: Resolve break-check cache key
+        id: break-check-key
+        run: echo "ref=${BREAK_CHECK_PACKAGE##*@}" >> "$GITHUB_OUTPUT"
+
       - name: Restore baseline from cache
         id: baseline-cache
         uses: actions/cache/restore@v4
         with:
           path: .api-snapshots-baseline
-          key: snapi-baseline-${{ github.event.pull_request.base.sha }}
+          # Keyed on the break-check commit too, so bumping break-check misses the
+          # stale baseline and the worktree fallback below rebuilds it with the
+          # same version the PR runs (see publish-baseline for the rationale).
+          key: break-check-baseline-${{ steps.break-check-key.outputs.ref }}-${{ github.event.pull_request.base.sha }}
 
       - name: Build current declarations
-        run: pnpm turbo build:declarations $TURBO_ARGS $SNAPI_FILTERS
+        run: pnpm turbo build:declarations $TURBO_ARGS $BREAK_CHECK_FILTERS
 
       - name: Fetch base commit
         if: steps.baseline-cache.outputs.cache-matched-key == ''
@@ -127,31 +179,48 @@ jobs:
         if: steps.baseline-cache.outputs.cache-matched-key == ''
         run: |
           mkdir -p .worktrees
-          git worktree add --detach .worktrees/snapi-baseline "${{ github.event.pull_request.base.sha }}"
-          cp snapi.config.json .worktrees/snapi-baseline/snapi.config.json
+          git worktree add --detach .worktrees/break-check-baseline "${{ github.event.pull_request.base.sha }}"
+          # Snapshot the base ref with the coverage it actually had. Only seed the
+          # config when the base tracks no coverage at all; otherwise packages
+          # newly added to coverage in this PR get diffed against a baseline that
+          # never tracked them (every export reads as a phantom change against the
+          # base's bundled .d.ts), and the base ref may not even build their
+          # declarations yet. A base from before this rename still names its config
+          # snapi.config.json, so check both names. This reads the base's real
+          # coverage; it is not rename-compat, and goes no-op once main carries
+          # break-check.config.json.
+          if [ ! -f .worktrees/break-check-baseline/break-check.config.json ] && [ ! -f .worktrees/break-check-baseline/snapi.config.json ]; then
+            cp break-check.config.json .worktrees/break-check-baseline/break-check.config.json
+          fi
 
       - name: Install baseline dependencies
         if: steps.baseline-cache.outputs.cache-matched-key == ''
-        working-directory: .worktrees/snapi-baseline
+        working-directory: .worktrees/break-check-baseline
         run: pnpm install --frozen-lockfile
 
       - name: Build baseline declarations
         if: steps.baseline-cache.outputs.cache-matched-key == ''
-        working-directory: .worktrees/snapi-baseline
-        run: pnpm turbo build:declarations $TURBO_ARGS $SNAPI_FILTERS
+        working-directory: .worktrees/break-check-baseline
+        # --continue past per-package failures and don't fail the step: the base
+        # ref may not build declarations for packages that only gained
+        # build:declarations support in this PR. break-check snapshots only the
+        # base's own coverage below, so a partial build is fine; a needed package
+        # that fails to build still surfaces when `break-check snapshot` finds no
+        # .d.ts.
+        run: pnpm turbo build:declarations $TURBO_ARGS $BREAK_CHECK_FILTERS --continue || true
 
       - name: Generate baseline API snapshots
         if: steps.baseline-cache.outputs.cache-matched-key == ''
-        working-directory: .worktrees/snapi-baseline
+        working-directory: .worktrees/break-check-baseline
         run: |
-          pnpm dlx --package "$SNAPI_PACKAGE" snapi snapshot \
+          pnpm dlx --package "$BREAK_CHECK_PACKAGE" break-check snapshot \
             --output "$GITHUB_WORKSPACE/.api-snapshots-baseline"
 
       - name: Detect API changes
         env:
-          SNAPI_ANTHROPIC_API_KEY: ${{ secrets.SNAPI_ANTHROPIC_API_KEY }}
+          BREAK_CHECK_ANTHROPIC_API_KEY: ${{ secrets.BREAK_CHECK_ANTHROPIC_API_KEY }}
         run: |
-          pnpm dlx --package "$SNAPI_PACKAGE" snapi detect \
+          pnpm dlx --package "$BREAK_CHECK_PACKAGE" break-check detect \
             --baseline .api-snapshots-baseline \
             --output api-changes-report.md \
             --fail-on-breaking
@@ -165,38 +234,67 @@ jobs:
           if-no-files-found: ignore
           retention-days: 5
 
-      - name: Build snapi comment body
+      - name: Post break-check report
         if: always()
-        id: report
-        run: |
-          if [ ! -f api-changes-report.md ]; then
-            exit 0
-          fi
-          {
-            echo 'body<<SNAPI_REPORT_EOF'
-            echo '<!-- snapi-report -->'
-            if grep -q '## No API Changes Detected' api-changes-report.md; then
-              echo '**Snapi**: no API changes detected in `@clerk/backend`, `@clerk/clerk-js`, `@clerk/nextjs`, `@clerk/react`, `@clerk/shared`, `@clerk/ui`.'
-            else
-              cat api-changes-report.md
-            fi
-            echo 'SNAPI_REPORT_EOF'
-          } >> "$GITHUB_OUTPUT"
-
-      - name: Find existing snapi comment
-        if: always() && steps.report.outputs.body != ''
-        id: find-comment
-        uses: peter-evans/find-comment@3eae4d37986fb5a8592848f6a574fdf654e61f9e # v3.1.0
+        uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7
+        env:
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
         with:
-          issue-number: ${{ github.event.pull_request.number }}
-          comment-author: 'github-actions[bot]'
-          body-includes: '<!-- snapi-report -->'
+          script: |
+            const fs = require('fs');
+            const reportPath = 'api-changes-report.md';
+            if (!fs.existsSync(reportPath)) {
+              core.info('No break-check report found; skipping comment.');
+              return;
+            }
 
-      - name: Post snapi report
-        if: always() && steps.report.outputs.body != ''
-        uses: peter-evans/create-or-update-comment@23ff15729ef2fc348714a3bb66d2f655ca9066f2 # v3.1.0
-        with:
-          comment-id: ${{ steps.find-comment.outputs.comment-id }}
-          issue-number: ${{ github.event.pull_request.number }}
-          body: ${{ steps.report.outputs.body }}
-          edit-mode: replace
+            const marker = '<!-- break-check-report -->';
+            const report = fs.readFileSync(reportPath, 'utf-8');
+
+            let body;
+            if (report.includes('## No API Changes Detected')) {
+              body = `${marker}\n**Break Check**: no API changes detected across the tracked packages.`;
+            } else {
+              // GitHub rejects comment bodies over 65536 chars. Read the report
+              // from disk and post via the API so we never hit an arg-length
+              // limit, and truncate with a pointer to the full artifact when a
+              // genuinely large diff would overflow the comment.
+              const LIMIT = 64000;
+              const head = `${marker}\n`;
+              if (head.length + report.length <= LIMIT) {
+                body = head + report;
+              } else {
+                const notice =
+                  `\n\n> **Note**\n> Report truncated to fit GitHub's comment limit. ` +
+                  `The full report is attached as the \`api-changes-report\` artifact on ` +
+                  `[this run](${process.env.RUN_URL}).\n`;
+                const budget = LIMIT - head.length - notice.length;
+                body = head + report.slice(0, budget) + notice;
+              }
+            }
+
+            const comments = await github.paginate(github.rest.issues.listComments, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              per_page: 100,
+            });
+            const existing = comments.find(
+              (c) => c.user?.type === 'Bot' && c.body && c.body.includes(marker),
+            );
+
+            if (existing) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: existing.id,
+                body,
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body,
+              });
+            }

.github/workflows/api-changes.yml

@@ -0,0 +1,27 @@
+{
+  "packages": [
+    "packages/astro",
+    "packages/backend",
+    "packages/chrome-extension",
+    "packages/clerk-js",
+    "packages/expo",
+    "packages/expo-passkeys",
+    "packages/express",
+    "packages/fastify",
+    "packages/hono",
+    "packages/localizations",
+    "packages/nextjs",
+    "packages/nuxt",
+    "packages/react",
+    "packages/react-router",
+    "packages/shared",
+    "packages/tanstack-react-start",
+    "packages/testing",
+    "packages/ui",
+    "packages/vue"
+  ],
+  "snapshotDir": ".api-snapshots",
+  "mainBranch": "main",
+  "checkVersionBump": true,
+  "outputFormat": "markdown"
+}

break-check.config.json

@@ -77,8 +77,8 @@
     "types.ts"
   ],
   "scripts": {
-    "build": "tsup --onSuccess \"pnpm build:dts\" && pnpm copy:components",
-    "build:dts": "tsc --emitDeclarationOnly --declaration",
+    "build": "tsup --onSuccess \"pnpm build:declarations\" && pnpm copy:components",
+    "build:declarations": "tsc -p tsconfig.declarations.json",
     "copy:components": "rm -rf ./components && mkdir -p ./components/ && cp  -r ./src/astro-components/* ./components/ && cp ./src/types.ts ./",
     "dev": "tsup --watch",
     "dev:pub": "pnpm dev -- --env.publish",

packages/astro/package.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist",
+    "declarationDir": "./dist/types",
+    "skipLibCheck": true
+  },
+  "exclude": ["node_modules", "dist", "build", "src/astro-components/**/*.ts", "**/__tests__/**/*"]
+}

packages/astro/tsconfig.declarations.json

@@ -21,7 +21,7 @@ export default defineConfig(overrideOptions => {
     ],
     dts: true,
     minify: false,
-    onSuccess: shouldPublish ? 'pnpm build:dts && pkglab pub --ping' : 'pnpm build:dts',
+    onSuccess: shouldPublish ? 'pnpm build:declarations && pkglab pub --ping' : 'pnpm build:declarations',
     define: {
       PACKAGE_NAME: `"${name}"`,
       PACKAGE_VERSION: `"${version}"`,

packages/astro/tsup.config.ts

@@ -62,6 +62,7 @@
   ],
   "scripts": {
     "build": "pnpm clean && tsup",
+    "build:declarations": "tsc -p tsconfig.declarations.json",
     "clean": "rimraf ./dist",
     "dev": "tsup --watch",
     "dev:pub": "pnpm dev -- --env.publish",

packages/express/package.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "emitDeclarationOnly": true,
+    "skipLibCheck": true
+  },
+  "exclude": ["node_modules", "dist", "**/__tests__/**/*"]
+}

packages/express/tsconfig.declarations.json

@@ -61,6 +61,7 @@
   ],
   "scripts": {
     "build": "tsup --env.NODE_ENV production",
+    "build:declarations": "tsc -p tsconfig.declarations.json",
     "clean": "rimraf ./dist",
     "dev": "tsup --watch",
     "dev:pub": "pnpm dev -- --env.publish",

packages/fastify/package.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "emitDeclarationOnly": true,
+    "skipLibCheck": true
+  },
+  "exclude": ["node_modules", "dist", "**/__tests__/**/*"]
+}