From 7dbae147093631d840e313212ba1c3ee64e92dc5 Mon Sep 17 00:00:00 2001
From: Itay Brenner <itay.brenner@sentry.io>
Date: Thu, 19 Mar 2026 22:22:45 -0300
Subject: [PATCH 1/7] ci(01-02): add SentryCrash import ratchet script

- Count direct SentryCrash imports from SDK sources
- Fail if count exceeds baseline of 59
- Add check-sentrycrash-imports Makefile target
---
 Makefile                             |  8 +++++++
 scripts/check-sentrycrash-imports.sh | 32 ++++++++++++++++++++++++++++
 2 files changed, 40 insertions(+)
 create mode 100755 scripts/check-sentrycrash-imports.sh

diff --git a/Makefile b/Makefile
index bd39d9057d..cf88f252e0 100644
--- a/Makefile
+++ b/Makefile
@@ -95,6 +95,14 @@ update-versions:
 check-versions:
 	./scripts/check-tooling-versions.sh
 
+## Check SentryCrash imports
+#
+# CI ratchet that ensures the number of direct SentryCrash header imports
+# from SDK source files does not increase beyond the established baseline.
+.PHONY: check-sentrycrash-imports
+check-sentrycrash-imports:
+	@./scripts/check-sentrycrash-imports.sh
+
 # ============================================================================
 # BUILDING
 # ============================================================================
diff --git a/scripts/check-sentrycrash-imports.sh b/scripts/check-sentrycrash-imports.sh
new file mode 100755
index 0000000000..a1cdaefbee
--- /dev/null
+++ b/scripts/check-sentrycrash-imports.sh
@@ -0,0 +1,32 @@
+#!/bin/bash
+
+# CI ratchet: ensures SentryCrash import count doesn't increase in SDK sources.
+# Decrease MAX_IMPORTS as phases eliminate imports. Never increase it.
+
+set -euo pipefail
+
+# Source CI utilities for proper logging
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+# shellcheck source=./ci-utils.sh disable=SC1091
+source "$SCRIPT_DIR/ci-utils.sh"
+
+MAX_IMPORTS=59
+
+count=$(grep -rn '#import.*SentryCrash' Sources/Sentry Sources/Swift \
+    --include='*.m' --include='*.h' --include='*.c' --include='*.mm' \
+    | grep -vc 'Sources/SentryCrash/' \
+    | tr -d ' ')
+
+if [ "$count" -gt "$MAX_IMPORTS" ]; then
+    log_error "SentryCrash import count increased from $MAX_IMPORTS to $count"
+    log_error "New imports from SDK files into SentryCrash headers are not allowed."
+    log_error "Use the SentryCrashReporter protocol instead."
+    echo ""
+    log_notice "Offending imports:"
+    grep -rn '#import.*SentryCrash' Sources/Sentry Sources/Swift \
+        --include='*.m' --include='*.h' --include='*.c' --include='*.mm' \
+        | grep -v 'Sources/SentryCrash/'
+    exit 1
+fi
+
+log_notice "SentryCrash import ratchet: $count / $MAX_IMPORTS (OK)"

From 8e08b3ec3af697829441dd446bbb3232484f627f Mon Sep 17 00:00:00 2001
From: Itay Brenner <itay.brenner@sentry.io>
Date: Thu, 19 Mar 2026 22:23:18 -0300
Subject: [PATCH 2/7] ci(01-02): wire SentryCrash import ratchet into PR checks

- Add sentrycrash-import-ratchet job to fast-pr-checks workflow
- Run on ubuntu-latest (only needs grep, no Xcode)
- Gate fast-checks-required on ratchet passing
---
 .github/workflows/fast-pr-checks.yml | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/fast-pr-checks.yml b/.github/workflows/fast-pr-checks.yml
index bef598692f..65f832bb72 100644
--- a/.github/workflows/fast-pr-checks.yml
+++ b/.github/workflows/fast-pr-checks.yml
@@ -57,8 +57,23 @@ jobs:
       scheme: Sentry
       run_on_cirrus_labs: true
 
+  sentrycrash-import-ratchet:
+    name: SentryCrash Import Ratchet
+    if: needs.files-changed.outputs.run_unit_tests_for_prs == 'true'
+    needs: files-changed
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - name: Check SentryCrash import count
+        run: ./scripts/check-sentrycrash-imports.sh
+
   fast-checks-required:
-    needs: [files-changed, fast-xcframework-slices, fast-unit-tests]
+    needs: [
+      files-changed,
+      fast-xcframework-slices,
+      fast-unit-tests,
+      sentrycrash-import-ratchet,
+    ]
     name: Fast PR Checks
     if: always()
     runs-on: ubuntu-latest

From 27eb99926683cb22649b3d2e39f5efb53833b59a Mon Sep 17 00:00:00 2001
From: Itay Brenner <itay.brenner@sentry.io>
Date: Mon, 23 Mar 2026 12:28:29 +0100
Subject: [PATCH 3/7] Fix script to cover imports with whitespaces

---
 scripts/check-sentrycrash-imports.sh | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/scripts/check-sentrycrash-imports.sh b/scripts/check-sentrycrash-imports.sh
index a1cdaefbee..6d23b61d16 100755
--- a/scripts/check-sentrycrash-imports.sh
+++ b/scripts/check-sentrycrash-imports.sh
@@ -10,21 +10,24 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=./ci-utils.sh disable=SC1091
 source "$SCRIPT_DIR/ci-utils.sh"
 
-MAX_IMPORTS=59
+# Baseline count of #import / #include lines referencing SentryCrash from SDK sources
+# (excludes Sources/SentryCrash/). Pattern allows whitespace after '#' so indented
+# directives under #if are counted, and matches #include as well as #import.
+MAX_IMPORTS=85
 
-count=$(grep -rn '#import.*SentryCrash' Sources/Sentry Sources/Swift \
-    --include='*.m' --include='*.h' --include='*.c' --include='*.mm' \
+count=$(grep -rnE '#[[:space:]]*(import|include).*SentryCrash' Sources/Sentry Sources/Swift \
+    --include='*.m' --include='*.h' --include='*.c' --include='*.mm' --include='*.cpp' \
     | grep -vc 'Sources/SentryCrash/' \
     | tr -d ' ')
 
 if [ "$count" -gt "$MAX_IMPORTS" ]; then
     log_error "SentryCrash import count increased from $MAX_IMPORTS to $count"
-    log_error "New imports from SDK files into SentryCrash headers are not allowed."
+    log_error "New #import / #include of SentryCrash from SDK files is not allowed."
     log_error "Use the SentryCrashReporter protocol instead."
     echo ""
     log_notice "Offending imports:"
-    grep -rn '#import.*SentryCrash' Sources/Sentry Sources/Swift \
-        --include='*.m' --include='*.h' --include='*.c' --include='*.mm' \
+    grep -rnE '#[[:space:]]*(import|include).*SentryCrash' Sources/Sentry Sources/Swift \
+        --include='*.m' --include='*.h' --include='*.c' --include='*.mm' --include='*.cpp' \
         | grep -v 'Sources/SentryCrash/'
     exit 1
 fi

From 306592cb26ba98ec1b4100cd75eebf356ea58a44 Mon Sep 17 00:00:00 2001
From: Itay Brenner <itay.brenner@sentry.io>
Date: Mon, 23 Mar 2026 12:31:45 +0100
Subject: [PATCH 4/7] Update SentryCrash import check script to focus on
 specific source directories

---
 scripts/check-sentrycrash-imports.sh | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/scripts/check-sentrycrash-imports.sh b/scripts/check-sentrycrash-imports.sh
index 6d23b61d16..fce9bf83ee 100755
--- a/scripts/check-sentrycrash-imports.sh
+++ b/scripts/check-sentrycrash-imports.sh
@@ -10,15 +10,14 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 # shellcheck source=./ci-utils.sh disable=SC1091
 source "$SCRIPT_DIR/ci-utils.sh"
 
-# Baseline count of #import / #include lines referencing SentryCrash from SDK sources
-# (excludes Sources/SentryCrash/). Pattern allows whitespace after '#' so indented
-# directives under #if are counted, and matches #include as well as #import.
+# Baseline count of #import / #include lines referencing SentryCrash in Sources/Sentry
+# and Sources/Swift only (not Sources/SentryCrash). Pattern allows whitespace after '#'
+# so indented directives under #if are counted; matches #include and #import.
 MAX_IMPORTS=85
 
 count=$(grep -rnE '#[[:space:]]*(import|include).*SentryCrash' Sources/Sentry Sources/Swift \
     --include='*.m' --include='*.h' --include='*.c' --include='*.mm' --include='*.cpp' \
-    | grep -vc 'Sources/SentryCrash/' \
-    | tr -d ' ')
+    | wc -l | tr -d ' ')
 
 if [ "$count" -gt "$MAX_IMPORTS" ]; then
     log_error "SentryCrash import count increased from $MAX_IMPORTS to $count"
@@ -27,8 +26,7 @@ if [ "$count" -gt "$MAX_IMPORTS" ]; then
     echo ""
     log_notice "Offending imports:"
     grep -rnE '#[[:space:]]*(import|include).*SentryCrash' Sources/Sentry Sources/Swift \
-        --include='*.m' --include='*.h' --include='*.c' --include='*.mm' --include='*.cpp' \
-        | grep -v 'Sources/SentryCrash/'
+        --include='*.m' --include='*.h' --include='*.c' --include='*.mm' --include='*.cpp'
     exit 1
 fi
 

From 275b73d8f2777c5d8faa0127f4fece0dd9ac7450 Mon Sep 17 00:00:00 2001
From: Itay Brenner <itay.brenner@sentry.io>
Date: Mon, 23 Mar 2026 12:41:00 +0100
Subject: [PATCH 5/7] Extract check to a new workflow

---
 .github/file-filters.yml                      | 22 +++++++
 .github/workflows/fast-pr-checks.yml          | 11 ----
 .../workflows/lint-sentrycrash-imports.yml    | 59 +++++++++++++++++++
 3 files changed, 81 insertions(+), 11 deletions(-)
 create mode 100644 .github/workflows/lint-sentrycrash-imports.yml

diff --git a/.github/file-filters.yml b/.github/file-filters.yml
index 186bba5caf..1fe162372e 100644
--- a/.github/file-filters.yml
+++ b/.github/file-filters.yml
@@ -172,6 +172,28 @@ run_lint_clang_formatting_for_prs: &run_lint_clang_formatting_for_prs
   - "Makefile"
   - "Brewfile*"
 
+# Same ObjC/C/C++ source patterns as run_lint_clang_formatting_for_prs; omits clang-format-only paths.
+run_sentrycrash_import_ratchet_for_prs:
+  - "**/*.h"
+  - "**/*.hpp"
+  - "**/*.c"
+  - "**/*.cpp"
+  - "**/*.m"
+  - "**/*.mm"
+
+  # GH Actions
+  - ".github/workflows/lint-sentrycrash-imports.yml"
+  - ".github/file-filters.yml"
+
+  # Scripts
+  - "scripts/check-sentrycrash-imports.sh"
+  - "scripts/ci-diagnostics.sh"
+  - "scripts/ci-utils.sh"
+
+  # Build configuration
+  - "Makefile"
+  - "Brewfile*"
+
 run_objc_conversion_analysis_for_prs: &run_objc_conversion_analysis_for_prs
   - "SwiftConversion/**"
 
diff --git a/.github/workflows/fast-pr-checks.yml b/.github/workflows/fast-pr-checks.yml
index 65f832bb72..c79e5e32a7 100644
--- a/.github/workflows/fast-pr-checks.yml
+++ b/.github/workflows/fast-pr-checks.yml
@@ -57,22 +57,11 @@ jobs:
       scheme: Sentry
       run_on_cirrus_labs: true
 
-  sentrycrash-import-ratchet:
-    name: SentryCrash Import Ratchet
-    if: needs.files-changed.outputs.run_unit_tests_for_prs == 'true'
-    needs: files-changed
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
-      - name: Check SentryCrash import count
-        run: ./scripts/check-sentrycrash-imports.sh
-
   fast-checks-required:
     needs: [
       files-changed,
       fast-xcframework-slices,
       fast-unit-tests,
-      sentrycrash-import-ratchet,
     ]
     name: Fast PR Checks
     if: always()
diff --git a/.github/workflows/lint-sentrycrash-imports.yml b/.github/workflows/lint-sentrycrash-imports.yml
new file mode 100644
index 0000000000..1f8bdfafd5
--- /dev/null
+++ b/.github/workflows/lint-sentrycrash-imports.yml
@@ -0,0 +1,59 @@
+name: Lint SentryCrash Imports
+
+on:
+  push:
+    branches:
+      - main
+      - v8.x
+
+  pull_request:
+
+# Concurrency configuration:
+# - We use workflow-specific concurrency groups to prevent multiple lint runs on the same code,
+#   as linting checks are deterministic and don't require parallel validation.
+# - For pull requests, we cancel in-progress runs when new commits are pushed since only the
+#   latest linting matters for merge decisions.
+# - For main branch pushes, we never cancel to ensure the ratchet runs for every push.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  files-changed:
+    name: Detect File Changes
+    runs-on: ubuntu-latest
+    outputs:
+      run_sentrycrash_import_ratchet_for_prs: ${{ steps.changes.outputs.run_sentrycrash_import_ratchet_for_prs }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - name: Get changed files
+        id: changes
+        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        with:
+          token: ${{ github.token }}
+          filters: .github/file-filters.yml
+
+  check-imports:
+    name: Check SentryCrash Imports
+    if: github.event_name != 'pull_request' || needs.files-changed.outputs.run_sentrycrash_import_ratchet_for_prs == 'true'
+    needs: files-changed
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - name: Check SentryCrash import count
+        run: ./scripts/check-sentrycrash-imports.sh
+
+      - name: Run CI Diagnostics
+        if: failure()
+        run: ./scripts/ci-diagnostics.sh
+
+  lint_sentrycrash_imports-required-check:
+    needs: [files-changed, check-imports]
+    name: Lint SentryCrash Imports
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check for failures
+        if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled')
+        run: |
+          echo "One of the SentryCrash import ratchet jobs has failed." && exit 1

From da820add3a8aa9172fb30a44e3f29ee17c8b73bc Mon Sep 17 00:00:00 2001
From: Itay Brenner <itay.brenner@sentry.io>
Date: Fri, 24 Apr 2026 15:39:54 -0300
Subject: [PATCH 6/7] Bump number to 86

---
 scripts/check-sentrycrash-imports.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/scripts/check-sentrycrash-imports.sh b/scripts/check-sentrycrash-imports.sh
index fce9bf83ee..5d682f1ac0 100755
--- a/scripts/check-sentrycrash-imports.sh
+++ b/scripts/check-sentrycrash-imports.sh
@@ -13,7 +13,7 @@ source "$SCRIPT_DIR/ci-utils.sh"
 # Baseline count of #import / #include lines referencing SentryCrash in Sources/Sentry
 # and Sources/Swift only (not Sources/SentryCrash). Pattern allows whitespace after '#'
 # so indented directives under #if are counted; matches #include and #import.
-MAX_IMPORTS=85
+MAX_IMPORTS=86
 
 count=$(grep -rnE '#[[:space:]]*(import|include).*SentryCrash' Sources/Sentry Sources/Swift \
     --include='*.m' --include='*.h' --include='*.c' --include='*.mm' --include='*.cpp' \

From 8028b90429428d5e3bf1b646be96798c695c7a0d Mon Sep 17 00:00:00 2001
From: Itay Brenner <itay.brenner@sentry.io>
Date: Thu, 30 Apr 2026 13:50:21 -0300
Subject: [PATCH 7/7] fix: Update SentryCrash import check to include .hpp
 files

---
 scripts/check-sentrycrash-imports.sh | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/scripts/check-sentrycrash-imports.sh b/scripts/check-sentrycrash-imports.sh
index 5d682f1ac0..f45f7971f0 100755
--- a/scripts/check-sentrycrash-imports.sh
+++ b/scripts/check-sentrycrash-imports.sh
@@ -17,7 +17,8 @@ MAX_IMPORTS=86
 
 count=$(grep -rnE '#[[:space:]]*(import|include).*SentryCrash' Sources/Sentry Sources/Swift \
     --include='*.m' --include='*.h' --include='*.c' --include='*.mm' --include='*.cpp' \
-    | wc -l | tr -d ' ')
+    --include='*.hpp' \
+    | wc -l | tr -d ' ' || true)
 
 if [ "$count" -gt "$MAX_IMPORTS" ]; then
     log_error "SentryCrash import count increased from $MAX_IMPORTS to $count"
@@ -26,7 +27,8 @@ if [ "$count" -gt "$MAX_IMPORTS" ]; then
     echo ""
     log_notice "Offending imports:"
     grep -rnE '#[[:space:]]*(import|include).*SentryCrash' Sources/Sentry Sources/Swift \
-        --include='*.m' --include='*.h' --include='*.c' --include='*.mm' --include='*.cpp'
+        --include='*.m' --include='*.h' --include='*.c' --include='*.mm' --include='*.cpp' \
+        --include='*.hpp'
     exit 1
 fi