@mcamdali/sdkbump 0.0.0-stage → 0.1.3

package/README.ko.md

@@ -0,0 +1,250 @@
+<!-- i18n-source: README.md@49073c524eb2b7aad433b6794961ec40869c1170 status=reviewed -->
+<!-- brand:start -->
+
+<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/banner-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/banner-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/banner-light.svg" alt="sdkbump: Checks native iOS, Flutter and React Native apps for the iOS 27 SDK changes and names the fix for each."></picture></p>
+
+<!-- lang-selector:start -->
+<p align="center"><a href="README.md">English</a> · <a href="README.tr.md">Türkçe</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.es.md">Español</a> · <a href="README.de.md">Deutsch</a> · <a href="README.fr.md">Français</a> · <a href="README.pt-BR.md">Português (Brasil)</a> · <a href="README.ru.md">Русский</a></p>
+<!-- lang-selector:end -->
+
+<p align="center">
+<a href="https://github.com/muhittincamdali/sdkbump/actions/workflows/ci.yml"><img src="https://github.com/muhittincamdali/sdkbump/actions/workflows/ci.yml/badge.svg" alt="CI 상태"></a>
+<a href="https://github.com/muhittincamdali/sdkbump/releases"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-version-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-version-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-version-light.svg" alt="최신 버전: v0.1.2"></picture></a>
+<a href="https://github.com/muhittincamdali/sdkbump/blob/main/package.json"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-language-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-language-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-language-light.svg" alt="언어 버전: Node.js 22.12+"></picture></a>
+<a href="https://github.com/muhittincamdali/sdkbump/blob/main/LICENSE"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-license-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-license-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-license-light.svg" alt="라이선스: MIT"></picture></a>
+</p>
+
+<p align="center">
+<a href="#빠른-시작"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-start-ko-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-start-ko-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-start-ko-light.svg" alt="시작하기"></picture></a>
+<a href="https://muhittincamdali.github.io/sdkbump/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-docs-ko-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-docs-ko-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-docs-ko-light.svg" alt="문서"></picture></a>
+<a href="https://github.com/muhittincamdali/sdkbump/tree/main/docs/guides"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-guides-ko-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-guides-ko-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-guides-ko-light.svg" alt="가이드"></picture></a>
+<a href="https://github.com/muhittincamdali/sdkbump/tree/main/examples"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-examples-ko-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-examples-ko-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-examples-ko-light.svg" alt="예제"></picture></a>
+</p>
+
+> 이 문서는 영어 README의 번역본입니다. 내용이 다를 경우 영어 버전이 최신입니다.
+
+<!-- brand:end -->
+
+Xcode 27로 빌드한 앱을 출시하기 전에: sdkbump는 네이티브 iOS, Flutter, React Native/Expo 프로젝트에서 iOS 27 SDK가 바꾸는 부분(우선 UIScene 생명 주기)을 검사하고, 각 항목에 어떤 해결 방법이 맞는지 알려 줍니다. 프로젝트 파일을 읽기만 하며, 빌드하거나 실행하거나 변경하지 않습니다.
+
+<picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/demo-rn-087-dark.svg"><source media="(prefers-color-scheme: light)" srcset="docs/media/demo-rn-087-light.svg"><img src="docs/media/demo-rn-087-light.svg" alt="React Native 0.87 앱에서 실행한 sdkbump: iOS 27 SDK로 빌드하면 실행되지 않음. SCN001은 scene 구성 없음, SCN002는 app delegate에서 window 생성이며, 해결 방법은 세 가지"></picture>
+
+<sub>실제 CLI에서 녹화했습니다. 대상은 <a href="fixtures/rn-087">rn-087 fixture</a>, 즉 <code>@react-native-community/cli init</code>으로 만든 React Native 0.87.1 앱입니다(<code>npm run demo</code>).</sub>
+
+## 주요 기능
+
+- **"실행될까?"에 답합니다.** scene을 선언하지 않은 앱은 Xcode 27로 빌드되지만 실행할 때 멈춥니다. sdkbump는 테스트 기기에서 직접 겪기 전에 이를 알려 주고, 바꿔야 할 파일을 알려 줍니다.
+- **네이티브, Flutter, React Native, Expo**를 같은 규칙 ID로 하나의 보고서에 담습니다. 출력은 텍스트, Markdown, JSON 중에서 고를 수 있고, CI용 종료 코드도 제공합니다.
+- **내 프로젝트에 맞는 해결 방법**: React Native 0.88 또는 직접 작성한 scene delegate, Expo SDK 57의 옵트인 또는 SDK 58, Flutter의 자동 마이그레이션 또는 수동 절차(sdkbump는 Flutter 마이그레이터와 같은 조건을 확인합니다), SwiftUI 앱이라면 SwiftUI API.
+- **조용히 깨지는 부분도**: 앱에 scene이 생기면 UIKit이 더 이상 사용하지 않는 app delegate 메서드와 launch option(링크, Handoff, 퀵 액션, 포그라운드와 백그라운드 전환), 그리고 올바른 window를 더 이상 찾지 못하는 window 조회.
+- **모든 설명에는 출처가 있습니다.** 규칙은 데이터로 관리되며([rules/ios27.json](rules/ios27.json)) 각 규칙은 Apple, Flutter, React Native, Expo가 직접 공개한 페이지를 인용합니다. 출처가 없는 규칙이 있으면 테스트가 실패합니다.
+- **iOS 27 시뮬레이터에서 확인했습니다**: SCN001과 SCN002의 배경이 되는 실행 실패와 검은 화면을 Xcode 27.0으로 재현했으며, 녹화본은 저장소에 있습니다.
+
+## 빠른 시작
+
+[Node.js](https://nodejs.org/) 22.12 이상이 필요합니다(`node --version`으로 확인할 수 있고, Mac에서는 `brew install node`로 설치할 수 있습니다). 그 외에는 필요한 것이 없습니다.
+
+**1. 앱 폴더에서 터미널을 엽니다.** `.xcodeproj`, `pubspec.yaml`, `package.json` 중 하나가 있는 폴더입니다.
+
+```sh
+cd path/to/YourApp
+```
+
+**2. sdkbump를 실행합니다.**
+
+```sh
+npx @mcamdali/sdkbump
+```
+
+npm 패키지 이름은 `@mcamdali/sdkbump`이고, 설치되는 명령은 `sdkbump`입니다. scope 없이 `npx sdkbump`를 실행하면 이 패키지가 실행되지 않습니다.
+
+**3. 프로젝트 이름 아래의 첫 번째 줄을 읽습니다.** "Fails to launch when built with the iOS 27 SDK"(iOS 27 SDK로 빌드하면 실행되지 않음)는 **ERROR** 항목을 고칠 때까지 앱이 실행 시점에 멈춘다는 뜻이며, 각 항목은 "How to fix" 목록의 어떤 해결 방법이 맞는지 알려 줍니다. **WARNING** 항목은 실행을 막지는 않지만, 앱에 scene이 생기면 동작하지 않게 됩니다. "Launch not determined"(실행 여부를 판단할 수 없음)는 sdkbump가 Info.plist를 읽지 못했다는 뜻이며, 어떤 파일을 왜 읽지 못했는지는 보고서 끝의 참고 사항에 나옵니다(아래 "한계" 참고).
+
+## iOS 27 SDK로 빌드하면 무엇이 달라지나요
+
+Apple의 [Transitioning to the UIKit scene-based life cycle](https://developer.apple.com/documentation/uikit/transitioning-to-the-uikit-scene-based-life-cycle)에서 인용합니다(번역).
+
+> iOS 27, iPadOS 27, Mac Catalyst 27, tvOS 27, visionOS 27부터는 최신 SDK로 빌드한 앱이 scene 기반 생명 주기를 채택해야 하며, 그렇지 않으면 실행되지 않습니다.
+
+1. **앱이 scene을 선언하지 않으면 실행할 때 멈춥니다.** Info.plist에 구성이 들어 있는 `UIApplicationSceneManifest`가 없고 `application(_:configurationForConnecting:options:)`도 없으면, UIKit은 "UIScene life cycle is required for apps built with this SDK"라는 메시지와 함께 프로세스를 종료합니다. 이 검사는 앱이 시작될 때 이루어지므로 컴파일러는 경고하지 않습니다. React Native 0.87 이하, 옵트인하지 않은 Expo SDK 57, Expo SDK 56 이하가 이런 앱을 만들며, Flutter 도구가 마이그레이션하지 못하는 Flutter 앱도 마찬가지입니다.
+2. **scene이 있으면 app delegate는 더 이상 UI 이벤트를 받지 못합니다.** 링크, user activity, 퀵 액션, 활성/백그라운드 전환은 scene delegate로 전달되며, app delegate가 만든 window는 화면에 나타나지 않습니다.
+
+[컴파일되는데도 충돌하는 이유](docs/guides/why-it-crashes.md)에서는 iOS 27.0 시뮬레이터에서 실행한 [실행 매트릭스](examples/launch-matrix/README.md)를 보여 줍니다.
+
+## sdkbump가 검사하는 항목
+
+| 규칙   | 심각도  | 항목                                                                                                                                                                         | iOS 27.0 시뮬레이터에서 확인한 결과                                |
+| ------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| SCN001 | error   | scene 구성이 없음: 구성된 `UIApplicationSceneManifest`도 `configurationForConnecting`도 없고 SwiftUI `App`도 아님. `ios/`가 없는 Expo는 SDK 버전과 `enableSceneSupport` 확인 | 실행할 때 멈춤                                                     |
+| SCN002 | error   | app delegate가 `UIWindow(frame:)`으로 window를 생성함                                                                                                                        | 앱에 scene이 생기면 검은 화면                                      |
+| SCN003 | warning | scene이 있으면 UIKit이 더 이상 사용하지 않는 app delegate 메서드와 launch option 키(13개). 단, scene delegate가 이미 처리하는 경우는 제외                                    | SwiftUI 앱에서 `applicationDidEnterBackground(_:)`가 호출되지 않음 |
+| SCN004 | warning | `UIApplication.shared.keyWindow`, `.windows` 또는 app delegate의 `window`를 통한 window 조회                                                                                 | 컴파일러의 deprecation 경고만 표시됨                               |
+
+규칙 데이터는 `ios27@2026.10.15`이며 Xcode 27.0(27A266a)을 기준으로 확인했습니다. React Native 또는 Expo에 `react-native-uiscene-bridge`나 `react-native-xcode27`이 설치되어 있으면, 이들이 실행 시점에 처리하는 항목은 해당 README에 적힌 한계와 함께 "처리됨"으로 표시되며 실행 실패로 처리하지 않습니다.
+
+## 설치
+
+npm에서 `sdkbump` 명령을 설치합니다(패키지 `@mcamdali/sdkbump`).
+
+```sh
+npm i -g @mcamdali/sdkbump
+sdkbump
+```
+
+프로젝트에서는 `npm install --save-dev @mcamdali/sdkbump`로 버전을 고정할 수 있고, 그다음 `npx sdkbump`가 그 사본을 실행합니다. 각 [GitHub 릴리스](https://github.com/muhittincamdali/sdkbump/releases)에는 같은 패키지가 `sdkbump-<버전>.tgz`로 `SHA256SUMS` 파일과 함께 들어 있으며, `npx`로 npm 없이 URL에서 바로 실행할 수 있습니다. `muhittincamdali/tap`용 Homebrew formula는 릴리스 워크플로가 준비합니다(tap의 첫 릴리스와 함께 제공할 계획입니다).
+
+## 사용법
+
+```text
+sdkbump [path] [options]
+```
+
+| 옵션                    | 설명                                                                   |
+| ----------------------- | ---------------------------------------------------------------------- |
+| `path`                  | 프로젝트 폴더 또는 `.xcodeproj`. 기본값은 현재 폴더                    |
+| `-f, --format <format>` | `tty`(기본값), `markdown`, `json`                                      |
+| `-o, --output <file>`   | 보고서를 터미널 대신 파일에 기록                                       |
+| `--fail-on <severity>`  | `error`(기본값), `warning`, `info`, `none`: 종료 코드가 1이 되는 기준  |
+| `--no-color`            | 터미널에서도 일반 텍스트로 출력(`NO_COLOR`와 `FORCE_COLOR`를 따릅니다) |
+
+종료 코드: `0`은 `--fail-on` 이상에서 처리되지 않은 항목이 없음, `1`은 그 이상의 항목이 있음, `2`는 잘못된 인수, iOS 프로젝트를 찾지 못함 또는 예기치 않은 오류입니다.
+
+sdkbump는 iOS 앱을 스스로 찾습니다. 네이티브 앱은 루트 또는 한 단계 아래에 있는 `.xcodeproj`, Flutter, React Native, Expo 앱은 `ios/`(Flutter 플러그인은 `example/ios/`)입니다. 프로젝트 파일에 있는 모든 iOS 앱 타깃, 각 타깃이 지정한 Info.plist(XML 또는 바이너리), 앱의 Swift 및 Objective-C 파일을 읽으며, Pods, `node_modules`, 빌드 결과물, 테스트는 건너뜁니다. `ios/`가 없는 Expo 앱은 package.json과 app.json으로 검사합니다.
+
+### Markdown 보고서를 코드와 함께 보관하기
+
+```sh
+npx @mcamdali/sdkbump --format markdown --output sdkbump.md
+```
+
+### 스크립트에서 JSON 보고서 사용하기
+
+```sh
+npx @mcamdali/sdkbump --format json > sdkbump.json
+```
+
+각 항목에는 `rule`, `severity`, `file`, `line`, `message`, 단계와 가이드가 담긴 `fix`, `alternatives`, `mitigation`(우회용 패키지가 처리하면 설정됩니다), `sources`가 있습니다. 구조는 `schemaVersion` 0이며 1.0 이전에 바뀔 수 있습니다. [examples/shell/launch-blockers.sh](examples/shell/launch-blockers.sh)는 `jq`로 이를 걸러 냅니다.
+
+### CI에서 실행하기
+
+[examples/github-actions/sdkbump.yml](examples/github-actions/sdkbump.yml)은 iOS 앱을 건드리는 모든 pull request의 작업 요약에 보고서를 추가하고, error가 있으면 작업을 실패시킵니다.
+
+### JavaScript에서 사용하기
+
+```js
+import { render, scan } from 'sdkbump';
+
+const report = await scan('path/to/app');
+console.log(report.verdict.text);
+console.log(render(report, 'markdown'));
+```
+
+실행해 볼 수 있는 예제는 [examples/api/verdicts.mjs](examples/api/verdicts.mjs)입니다.
+
+## 데모
+
+터미널 녹화본은 각 툴체인으로 만든 실제 프로젝트인 [fixtures](fixtures/README.md)에서 CLI를 실행해 얻은 것입니다.
+
+| 프로젝트                                      | 녹화본                                                                                 |
+| --------------------------------------------- | -------------------------------------------------------------------------------------- |
+| React Native 0.87.1 앱                        | 이 페이지 맨 위                                                                        |
+| AppDelegate를 수정한 Flutter 앱(Flutter 3.24) | [라이트](docs/media/demo-flutter-light.svg) · [다크](docs/media/demo-flutter-dark.svg) |
+| 어댑터 방식의 app delegate를 쓰는 SwiftUI 앱  | [라이트](docs/media/demo-swiftui-light.svg) · [다크](docs/media/demo-swiftui-dark.svg) |
+
+iOS 27.0 시뮬레이터(iPhone 17, Xcode 27.0으로 빌드)에서 네이티브 UIKit fixture는 실행할 때 멈추고, 같은 앱을 scene delegate로 옮기면 실행됩니다.
+
+<picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/demo-simulator-native-uikit-dark.svg"><source media="(prefers-color-scheme: light)" srcset="docs/media/demo-simulator-native-uikit-light.svg"><img src="docs/media/demo-simulator-native-uikit-light.svg" alt="iOS 27.0 시뮬레이터에서 실행한 scripts/simulator-check.sh native-uikit: 실행 4초 후에도 동작하지 않으며, UIKit의 출력은 Application failed to launch: UIScene life cycle is required for apps built with this SDK"></picture>
+
+<p align="center"><img src="docs/media/simulator/launched.png" width="480" alt="Xcode 27.0으로 빌드한 native-uikit-scenes와 native-swiftui fixture가 iOS 27.0이 설치된 iPhone 17 시뮬레이터에서 실행되는 모습"></p>
+
+2026년 10월 15일에 Node.js 26.11이 설치된 Mac(Apple silicon, M5 Max)에서 다른 작업이 실행 중인 상태로 측정했습니다. fixture 10개에 대한 `node dist/cli/main.js` 실행 100번을 한 세트로 세 세트를 돌렸고, Node.js 시작 시간을 포함한 세트별 중앙값은 0.11초, 0.12초, 0.19초, 가장 느린 실행은 0.33초였습니다. 컴퓨터 부하가 클수록 시간이 늘어납니다.
+
+## 상태
+
+| 기능                                                                               | 상태      |
+| ---------------------------------------------------------------------------------- | --------- |
+| 네이티브, Flutter(앱과 플러그인 예제), React Native, Expo 프로젝트 감지            | 동작함    |
+| 앱 자체의 Info.plist와 Swift/Objective-C 소스에 대한 SCN001부터 SCN004             | 동작함    |
+| 생태계와 버전에 따른 해결 방법 선택, Flutter 자동 마이그레이션 확인, 우회용 패키지 | 동작함    |
+| 터미널, Markdown, JSON 보고서, `--fail-on` 종료 코드                               | 동작함    |
+| 의존성: Pods, `node_modules`, Flutter 플러그인 소스(패키지 이름 포함)              | 예정(0.2) |
+| 우회 안내를 별도 규칙 SCN005로 제공, 15.0 미만 배포 대상에 대한 DPT001             | 예정(0.2) |
+| `--verify`: CLI에서 iOS 27 시뮬레이터로 빌드하고 실행                              | 예정(0.3) |
+| 패턴 대신 Swift/Objective-C 구문 트리, 빌드된 `.app` 검사, SiriKit deprecation     | 예정(0.5) |
+| 네이티브 앱용 `fix --dry-run`, SARIF 출력, GitHub Action                           | 예정(0.8) |
+| 안정된 규칙 스키마와 JSON 구조                                                     | 예정(1.0) |
+
+## 한계
+
+- **컴파일러가 아니라 패턴입니다.** 규칙은 주석과 문자열을 공백으로 바꾼 Swift와 Objective-C 텍스트에 적용하는 정규 표현식입니다. 생성된 코드, 매크로 안의 코드, 흔하지 않은 방식으로 작성한 코드는 놓치거나 잘못 잡을 수 있습니다. 구문 트리는 예정(0.5)입니다.
+- **앱 자체 소스만 읽습니다.** Pods, `node_modules`, Flutter 플러그인 등 의존성은 읽지 않으므로, UIKit이 더 이상 호출하지 않는 app delegate 메서드에 기대는 플러그인은 보고되지 않습니다. 의존성 검사는 예정(0.2)입니다.
+- **빌드 설정은 project.pbxproj에서만 읽습니다.** sdkbump는 프로젝트 파일에서 `INFOPLIST_FILE`과 `GENERATE_INFOPLIST_FILE`을 읽고 `$(SRCROOT)`, `$(PROJECT_DIR)`, `$(TARGET_NAME)`, `$(PRODUCT_NAME)`을 펼칩니다. `.xcconfig` 파일은 읽지 않고, 다른 빌드 설정도 펼치지 않으며, 프로젝트 폴더 밖의 Info.plist도 읽지 않습니다. 타깃의 Info.plist를 읽지 못하면 추측하는 대신 SCN001을 info 항목으로 보고하고 판정을 "Launch not determined"로 표시합니다.
+- **억제 파일이 없습니다.** 항목을 검토 완료로 표시할 수 없으며, 어떤 심각도에서 실행을 실패로 할지는 `--fail-on`으로 정합니다.
+- **파일만 읽습니다.** sdkbump는 앱을 빌드하거나 실행하지 않습니다. `--verify`는 예정(0.3)입니다.
+
+## 문서
+
+API 레퍼런스와 가이드: [muhittincamdali.github.io/sdkbump](https://muhittincamdali.github.io/sdkbump/).
+
+## 가이드
+
+- [컴파일되는데도 충돌하는 이유](docs/guides/why-it-crashes.md)
+- [네이티브 UIKit 및 SwiftUI 앱](docs/guides/native-ios.md)
+- [Flutter: 수정한 AppDelegate와 플러그인](docs/guides/flutter.md)
+- [0.88 이전의 React Native와 SDK 58 이전의 Expo](docs/guides/react-native-expo.md)
+- [네이티브 모듈 작성자용: 콜드 스타트 시 링크와 알림](docs/guides/native-module-authors.md)
+
+## 관련 도구
+
+같은 변경을 다루는 다른 프로젝트도 있습니다. 어느 것이 맞는지는 필요한 것에 따라 다릅니다.
+
+- [react-native-uiscene-bridge](https://github.com/Atomics-hub/react-native-uiscene-bridge)와 [react-native-xcode27](https://github.com/Atomics-hub/react-native-xcode27)은 코드를 바꾸지 않고도 실행 시점에 React Native 또는 Expo 앱이 실행되도록 합니다. 아직 업그레이드할 수 없을 때 적합하며, sdkbump는 이들을 인식합니다.
+- [auditor-uiscene](https://github.com/Anzell/auditor-uiscene)은 셸 스크립트로 Flutter 앱과 플러그인을 점검합니다.
+- Flutter의 자체 마이그레이터(3.41부터의 `flutter build ios`)는 수정하지 않은 Flutter 앱을 마이그레이션합니다.
+- [flutter_spm_doctor](https://pub.dev/packages/flutter_spm_doctor)는 Flutter 플러그인을 검사합니다.
+
+## 요구 사항
+
+| 툴체인  | 최소 버전 |
+| ------- | --------- |
+| Node.js | 22.12     |
+
+sdkbump에는 Xcode가 필요 없습니다. 파일을 읽기만 하므로 Linux에서도 실행됩니다. CI는 Node.js 22와 24(Linux)에서 테스트를 실행하며, 로컬에서는 280개가 모두 Mac(Apple silicon)의 Node.js 22.23, 24.22, 26.11에서 통과합니다. 시뮬레이터 녹화에는 Xcode 27이 설치된 Mac이 필요하며 CI에는 포함되지 않습니다.
+
+## 아키텍처
+
+```text
+path ─► detectProject      native | flutter | react-native | expo; iOS folder; versions
+     ─► collectApp         iOS app targets from project.pbxproj, their Info.plist (XML or binary),
+                           Swift and Objective-C sources with comments and strings blanked
+     ─► checkApp           SCN001…SCN004, fix per ecosystem and version, workaround packages
+          rules/ios27.json  what each rule says, fixes, sources (validated with zod)
+     ─► render             tty | markdown | json
+```
+
+- 감지 패턴은 주석과 문자열을 비워 둔 소스 텍스트에 대한 정규식이며, 필요한 곳에서는 app delegate나 scene delegate 안에 있는 것만 셉니다.
+- 규칙 데이터는 코드와 분리되어 있고 버전이 매겨져 있습니다(`ios27@2026.10.15`). 규칙, 해결 방법, 우회 방법에 출처가 없으면 테스트가 실패합니다.
+- CLI(`src/cli/`)는 인수를 해석하고, 색과 너비를 고르고, 종료 코드를 정하는 일만 합니다.
+
+## 로드맵
+
+[상태](#상태) 표를 참고하세요. 0.2에서는 의존성과 배포 대상, 0.3에서는 CLI에서 시뮬레이터 실행, 0.5에서는 구문 트리와 빌드된 앱 검사, 0.8에서는 자동 수정과 SARIF, 1.0에서는 안정된 스키마를 추가합니다. 각 릴리스의 변경 내용은 [CHANGELOG.md](CHANGELOG.md)에 있습니다.
+
+## FAQ
+
+**제 앱은 지금 iOS 27에서 잘 실행됩니다. 영향을 받나요?** Xcode 26 이하로 빌드했다면 이 검사는 해당 빌드에 적용되지 않습니다. 저희가 실행해 본 결과, iOS 26 SDK에 링크한 같은 코드는 iOS 27 시뮬레이터에서 실행되었습니다. Xcode 27로 하는 다음 빌드부터 적용됩니다.
+
+**sdkbump로 실제 기기 테스트를 대신할 수 있나요?** 아니요. 파일을 읽기만 합니다. 이 저장소의 시뮬레이터 녹화는 iOS 27.0 시뮬레이터에서 얻은 것이며, 여기서는 어떤 것도 실제 기기에서 실행하지 않았습니다.
+
+**왜 어떤 항목은 "처리됨"으로 표시되나요?** package.json에 있는 우회용 패키지(react-native-uiscene-bridge 또는 react-native-xcode27)가 실행 시점에 scene을 선언하기 때문입니다. 앱은 실행되지만 앱 자체에는 아직 scene 지원이 없습니다. 보고서에는 해당 패키지의 한계와 실제 해결 방법이 나옵니다.
+
+**sdkbump가 제 프로젝트를 변경하나요?** 아니요. 프로젝트를 읽기만 하고, 요청한 보고서만 기록합니다.
+
+
+## 기여하기
+
+기여를 환영합니다. pull request를 열기 전에 [기여 가이드](CONTRIBUTING.md)와 [행동 강령](https://github.com/muhittincamdali/.github/blob/main/CODE_OF_CONDUCT.md)을 읽어 주세요. 보안 문제는 [보안 정책](SECURITY.md)에 따라 비공개로 제보해 주세요.
+
+## 라이선스
+
+MIT 라이선스로 배포됩니다. 자세한 내용은 [LICENSE](LICENSE)를 참고하세요.

package/README.md

@@ -1,3 +1,323 @@
-# Temporary Holding Version
+<!-- brand:start -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/banner-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/banner-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/banner-light.svg" alt="sdkbump: Checks native iOS, Flutter and React Native apps for the iOS 27 SDK changes and names the fix for each."></picture></p>
+
+<!-- lang-selector:start -->
+<p align="center"><a href="README.md">English</a> · <a href="README.tr.md">Türkçe</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ko.md">한국어</a> · <a href="README.es.md">Español</a> · <a href="README.de.md">Deutsch</a> · <a href="README.fr.md">Français</a> · <a href="README.pt-BR.md">Português (Brasil)</a> · <a href="README.ru.md">Русский</a></p>
+<!-- lang-selector:end -->
+
+<p align="center">
+<a href="https://github.com/muhittincamdali/sdkbump/actions/workflows/ci.yml"><img src="https://github.com/muhittincamdali/sdkbump/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+<a href="https://github.com/muhittincamdali/sdkbump/releases"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-version-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-version-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-version-light.svg" alt="Latest version: v0.1.2"></picture></a>
+<a href="https://github.com/muhittincamdali/sdkbump/blob/main/package.json"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-language-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-language-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-language-light.svg" alt="Language version: Node.js 22.12+"></picture></a>
+<a href="https://github.com/muhittincamdali/sdkbump/blob/main/LICENSE"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-license-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-license-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/badge-license-light.svg" alt="License: MIT"></picture></a>
+</p>
+
+<p align="center">
+<a href="#quick-start"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-start-en-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-start-en-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-start-en-light.svg" alt="Get started"></picture></a>
+<a href="https://muhittincamdali.github.io/sdkbump/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-docs-en-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-docs-en-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-docs-en-light.svg" alt="Documentation"></picture></a>
+<a href="https://github.com/muhittincamdali/sdkbump/tree/main/docs/guides"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-guides-en-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-guides-en-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-guides-en-light.svg" alt="Guides"></picture></a>
+<a href="https://github.com/muhittincamdali/sdkbump/tree/main/examples"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-examples-en-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-examples-en-light.svg"><img src="https://raw.githubusercontent.com/muhittincamdali/sdkbump/main/.github/brand/button-examples-en-light.svg" alt="Examples"></picture></a>
+</p>
+
+<!-- brand:end -->
+
+Before you ship a build made with Xcode 27: sdkbump checks a native iOS, Flutter or React
+Native/Expo project for what the iOS 27 SDK changes, starting with the UIScene life cycle, and
+tells you which fix applies to each finding. It reads your project's files; it does not build,
+run or change anything.
+
+<picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/demo-rn-087-dark.svg"><source media="(prefers-color-scheme: light)" srcset="docs/media/demo-rn-087-light.svg"><img src="docs/media/demo-rn-087-light.svg" alt="sdkbump run on a React Native 0.87 app: fails to launch when built with the iOS 27 SDK; SCN001 no scene configuration and SCN002 window created in the app delegate, with three ways to fix it"></picture>
+
+<sub>Recorded from the real CLI on the <a href="fixtures/rn-087">rn-087 fixture</a>, a React
+Native 0.87.1 app from <code>@react-native-community/cli init</code> (<code>npm run demo</code>).</sub>
+
+## Highlights
+
+- **Answers "will it launch?"** An app that declares no scene builds with Xcode 27 and then stops
+  at launch. sdkbump says so before you find out on a test device, and names the files to change.
+- **Native, Flutter, React Native and Expo** in one report with the same rule IDs, as text,
+  Markdown or JSON, and an exit code for CI.
+- **The fix that applies to your project**: React Native 0.88 or a hand-written scene delegate,
+  Expo SDK 57's opt-in or SDK 58, Flutter's automatic migration or the manual steps (sdkbump
+  checks the same conditions as Flutter's migrator), or the SwiftUI API for a SwiftUI app.
+- **Quiet breakage too**: app delegate methods and launch options UIKit stops using once the app
+  has a scene (links, Handoff, quick actions, foreground and background), and window lookups that
+  no longer find the right window.
+- **Every statement has a source.** The rules are data ([rules/ios27.json](rules/ios27.json)) and
+  each one cites Apple's, Flutter's, React Native's or Expo's own pages; the tests fail if one
+  does not.
+- **Checked in the iOS 27 simulator**: the launch failure and the black screen behind SCN001 and
+  SCN002 were reproduced with Xcode 27.0, and the recordings are in the repository.
+
+## Quick start
+
+You need [Node.js](https://nodejs.org/) 22.12 or later (`node --version` prints it; on a Mac,
+`brew install node` installs it). Nothing else.
+
+**1. Open a terminal in your app's folder**, the one with the `.xcodeproj`, `pubspec.yaml` or
+`package.json`:
+
+```sh
+cd path/to/YourApp
+```
+
+**2. Run sdkbump:**
+
+```sh
+npx @mcamdali/sdkbump
+```
+
+The npm package is `@mcamdali/sdkbump`; the command it installs is `sdkbump`. An unscoped
+`npx sdkbump` does not run it.
+
+**3. Read the first line under your project's name.** "Fails to launch when built with the iOS 27
+SDK" means the app stops at launch until you fix the **ERROR** findings; each one says which fix
+from the "How to fix" list applies. **WARNING** findings do not stop the launch but stop working
+once the app has a scene. "Launch not determined" means sdkbump could not read an Info.plist; the
+notes at the end of the report say which one and why (see Limits below).
+
+## What changes when you build with the iOS 27 SDK
+
+From Apple's
+[Transitioning to the UIKit scene-based life cycle](https://developer.apple.com/documentation/uikit/transitioning-to-the-uikit-scene-based-life-cycle):
+
+> Beginning in iOS 27, iPadOS 27, Mac Catalyst 27, tvOS 27, and visionOS 27, apps built with the
+> latest SDK must adopt the scene-based life cycle or they fail to launch.
+
+1. **The app stops at launch if it declares no scene.** No `UIApplicationSceneManifest` with a
+   configuration in Info.plist and no `application(_:configurationForConnecting:options:)`: UIKit
+   ends the process with "UIScene life cycle is required for apps built with this SDK". The
+   compiler does not warn, because the check runs when the app starts. React Native 0.87 and
+   earlier, Expo SDK 57 without its opt-in and Expo SDK 56 and earlier create apps like this; so do
+   Flutter apps that the Flutter tool cannot migrate.
+2. **With a scene, the app delegate stops receiving UI events.** Links, user activities, quick
+   actions and the active/background transitions go to the scene delegate, and a window the app
+   delegate creates is never shown.
+
+[Why it compiles and still crashes](docs/guides/why-it-crashes.md) shows the
+[launch matrix](examples/launch-matrix/README.md) we ran in the iOS 27.0 simulator.
+
+## What sdkbump checks
+
+| Rule   | Severity | Finding                                                                                                                                                                                     | Seen in the iOS 27.0 simulator                                  |
+| ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| SCN001 | error    | No scene configuration: no configured `UIApplicationSceneManifest`, no `configurationForConnecting`, not a SwiftUI `App`; for Expo without `ios/`, the SDK version and `enableSceneSupport` | stops at launch                                                 |
+| SCN002 | error    | The app delegate creates the window with `UIWindow(frame:)`                                                                                                                                 | black screen once the app has a scene                           |
+| SCN003 | warning  | App delegate methods and launch option keys UIKit no longer uses with scenes (13 of them), unless the scene delegate already handles them                                                   | `applicationDidEnterBackground(_:)` not called in a SwiftUI app |
+| SCN004 | warning  | Window lookups through `UIApplication.shared.keyWindow`, `.windows` or the app delegate's `window`                                                                                          | compiler deprecation warnings only                              |
+
+Rule data `ios27@2026.10.15`, checked against Xcode 27.0 (27A266a). When React Native or Expo has
+`react-native-uiscene-bridge` or `react-native-xcode27` installed, the findings it handles at run
+time are shown as handled, with the limits from its README, and do not fail the run.
+
+## Installation
+
+Install the `sdkbump` command from npm (package `@mcamdali/sdkbump`):
+
+```sh
+npm i -g @mcamdali/sdkbump
+sdkbump
+```
+
+In a project, `npm install --save-dev @mcamdali/sdkbump` pins a version, and `npx sdkbump` then
+runs that copy. Each [GitHub release](https://github.com/muhittincamdali/sdkbump/releases) also
+carries the same package as `sdkbump-<version>.tgz` with a `SHA256SUMS` file; `npx` runs it from
+its URL without npm. A Homebrew formula for `muhittincamdali/tap` is
+prepared by the release workflow (planned with the first release of the tap).
+
+## Usage
+
+```text
+sdkbump [path] [options]
+```
+
+| Option                  | What it does                                                               |
+| ----------------------- | -------------------------------------------------------------------------- |
+| `path`                  | Project folder or `.xcodeproj`; default is the current folder              |
+| `-f, --format <format>` | `tty` (default), `markdown` or `json`                                      |
+| `-o, --output <file>`   | Write the report to a file instead of the terminal                         |
+| `--fail-on <severity>`  | `error` (default), `warning`, `info` or `none`: when the exit code is 1    |
+| `--no-color`            | Plain text even in a terminal (`NO_COLOR` and `FORCE_COLOR` are respected) |
+
+Exit codes: `0` nothing unhandled at or above `--fail-on`, `1` findings at or above it, `2` bad
+arguments, no iOS project found, or an unexpected error.
+
+sdkbump finds the iOS app on its own: an `.xcodeproj` at the root or one folder down for native
+apps, `ios/` for Flutter, React Native and Expo apps (`example/ios/` for a Flutter plugin). It
+reads every iOS app target in the project file, the Info.plist each one names (XML or binary),
+and the Swift and Objective-C files of the app, skipping Pods, `node_modules`, build output and
+tests. Expo apps without `ios/` are checked from package.json and app.json.
+
+### Keep a Markdown report with the code
+
+```sh
+npx @mcamdali/sdkbump --format markdown --output sdkbump.md
+```
+
+### Use the JSON report in scripts
+
+```sh
+npx @mcamdali/sdkbump --format json > sdkbump.json
+```
+
+Each finding has `rule`, `severity`, `file`, `line`, `message`, the `fix` with its steps and guide,
+`alternatives`, `mitigation` (set when a workaround package handles it) and `sources`. The layout
+is `schemaVersion` 0 and may change before 1.0.
+[examples/shell/launch-blockers.sh](examples/shell/launch-blockers.sh) filters it with `jq`.
+
+### Run it in CI
+
+[examples/github-actions/sdkbump.yml](examples/github-actions/sdkbump.yml) adds the report to the
+job summary of every pull request that touches the iOS app and fails the job on errors.
+
+### From JavaScript
+
+```js
+import { render, scan } from 'sdkbump';
+
+const report = await scan('path/to/app');
+console.log(report.verdict.text);
+console.log(render(report, 'markdown'));
+```
+
+A runnable version is [examples/api/verdicts.mjs](examples/api/verdicts.mjs).
+
+## Demo
+
+The terminal recordings come from the CLI on the [fixtures](fixtures/README.md), real projects
+made with each toolchain:
+
+| Project                                                  | Recording                                                                             |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| React Native 0.87.1 app                                  | top of this page                                                                      |
+| Flutter app with a customised AppDelegate (Flutter 3.24) | [light](docs/media/demo-flutter-light.svg) · [dark](docs/media/demo-flutter-dark.svg) |
+| SwiftUI app with an adaptor app delegate                 | [light](docs/media/demo-swiftui-light.svg) · [dark](docs/media/demo-swiftui-dark.svg) |
+
+In the iOS 27.0 simulator (iPhone 17, built with Xcode 27.0), the native UIKit fixture stops at
+launch and the same app moved to a scene delegate launches:
+
+<picture><source media="(prefers-color-scheme: dark)" srcset="docs/media/demo-simulator-native-uikit-dark.svg"><source media="(prefers-color-scheme: light)" srcset="docs/media/demo-simulator-native-uikit-light.svg"><img src="docs/media/demo-simulator-native-uikit-light.svg" alt="scripts/simulator-check.sh native-uikit on the iOS 27.0 simulator: not running 4 seconds after launch, with UIKit's line: Application failed to launch: UIScene life cycle is required for apps built with this SDK"></picture>
+
+<p align="center"><img src="docs/media/simulator/launched.png" width="480" alt="The native-uikit-scenes and native-swiftui fixtures running on an iPhone 17 simulator with iOS 27.0, built with Xcode 27.0"></p>
+
+Measured on 15 October 2026 on a Mac (Apple silicon, M5 Max) with Node.js 26.11 while other jobs
+were running on it: three sets of 100 runs of `node dist/cli/main.js` on the ten fixtures, Node.js
+start-up included. The medians of the three sets were 0.11, 0.12 and 0.19 seconds; the slowest
+run took 0.33 seconds. A busier machine gives longer times.
+
+## Status
+
+| Feature                                                                                       | Status        |
+| --------------------------------------------------------------------------------------------- | ------------- |
+| Native, Flutter (app and plugin example), React Native and Expo project detection             | works         |
+| SCN001 to SCN004 on the app's own Info.plist and Swift/Objective-C sources                    | works         |
+| Fix selection by ecosystem and version; Flutter auto-migration check; workaround packages     | works         |
+| Terminal, Markdown and JSON reports; `--fail-on` exit codes                                   | works         |
+| Dependencies: Pods, `node_modules` and Flutter plugin sources, with the package named         | planned (0.2) |
+| SCN005 workaround notice as its own rule; DPT001 deployment targets below 15.0                | planned (0.2) |
+| `--verify`: build and launch in the iOS 27 simulator from the CLI                             | planned (0.3) |
+| Swift/Objective-C syntax trees instead of patterns; built `.app` checks; SiriKit deprecations | planned (0.5) |
+| `fix --dry-run` for native apps, SARIF output, GitHub Action                                  | planned (0.8) |
+| Stable rule schema and JSON layout                                                            | planned (1.0) |
+
+## Limits
+
+- **Patterns, not a compiler.** The rules are regular expressions over Swift and Objective-C text
+  whose comments and strings are blanked. Code that is generated, hidden behind macros or written
+  in an unusual shape can be missed or matched by mistake. Syntax trees are planned (0.5).
+- **Only the app's own sources.** Pods, `node_modules`, Flutter plugins and other dependencies are
+  not read, so a plugin that relies on app delegate methods UIKit no longer calls is not reported.
+  Dependency checks are planned (0.2).
+- **Build settings from project.pbxproj only.** sdkbump reads `INFOPLIST_FILE` and
+  `GENERATE_INFOPLIST_FILE` from the project file and expands `$(SRCROOT)`, `$(PROJECT_DIR)`,
+  `$(TARGET_NAME)` and `$(PRODUCT_NAME)`. It does not read `.xcconfig` files or expand other build
+  settings, and it does not read an Info.plist outside the project folder. When it cannot read a
+  target's Info.plist, SCN001 is an info finding and the verdict is "Launch not determined"
+  instead of a guess.
+- **No suppression file.** A finding cannot be marked as reviewed; `--fail-on` decides which
+  severities fail the run.
+- **Files only.** sdkbump does not build or launch the app; `--verify` is planned (0.3).
+
+## Documentation
+
+API reference and guides: [muhittincamdali.github.io/sdkbump](https://muhittincamdali.github.io/sdkbump/).
+
+## Guides
+
+- [Why it compiles and still crashes](docs/guides/why-it-crashes.md)
+- [Native UIKit and SwiftUI apps](docs/guides/native-ios.md)
+- [Flutter: a custom AppDelegate and plugins](docs/guides/flutter.md)
+- [React Native before 0.88 and Expo before SDK 58](docs/guides/react-native-expo.md)
+- [Native module authors: links and notifications at cold start](docs/guides/native-module-authors.md)
+
+## Related tools
+
+Other projects work on the same change; which one fits depends on what you need:
+
+- [react-native-uiscene-bridge](https://github.com/Atomics-hub/react-native-uiscene-bridge) and
+  [react-native-xcode27](https://github.com/Atomics-hub/react-native-xcode27) make a React Native
+  or Expo app launch without code changes, at run time. They fit when you cannot upgrade yet;
+  sdkbump recognises them.
+- [auditor-uiscene](https://github.com/Anzell/auditor-uiscene) audits Flutter apps and their
+  plugins with a shell script.
+- Flutter's own migrator (`flutter build ios` from 3.41) migrates an unmodified Flutter app.
+- [flutter_spm_doctor](https://pub.dev/packages/flutter_spm_doctor) checks Flutter plugins.
+
+## Requirements
+
+| Toolchain | Minimum version |
+| --------- | --------------- |
+| Node.js   | 22.12           |
+
+sdkbump does not need Xcode: it reads files, so it also runs on Linux. CI runs the tests on
+Node.js 22 and 24 (Linux); locally all 280 pass on Node.js 22.23, 24.22 and 26.11 on a Mac (Apple
+silicon). The simulator recordings need a Mac with Xcode 27 and are not part of CI.
+
+## Architecture
+
+```text
+path ─► detectProject      native | flutter | react-native | expo; iOS folder; versions
+     ─► collectApp         iOS app targets from project.pbxproj, their Info.plist (XML or binary),
+                           Swift and Objective-C sources with comments and strings blanked
+     ─► checkApp           SCN001…SCN004, fix per ecosystem and version, workaround packages
+          rules/ios27.json  what each rule says, fixes, sources (validated with zod)
+     ─► render             tty | markdown | json
+```
+
+- Detection patterns are regular expressions over source text whose comments and strings are
+  blanked, and only count inside an app delegate or scene delegate where that matters.
+- The rule data is separate from the code and versioned (`ios27@2026.10.15`); a test fails when a
+  rule, fix or workaround has no source.
+- The CLI (`src/cli/`) only parses arguments, picks colours and widths, and sets the exit code.
+
+## Roadmap
+
+See the [Status](#status) table: 0.2 adds dependencies and deployment targets, 0.3 launching in
+the simulator from the CLI, 0.5 syntax trees and built-app checks, 0.8 fixes and SARIF, 1.0 a
+stable schema. [CHANGELOG.md](CHANGELOG.md) lists what each release changed.
+
+## FAQ
+
+**My app runs on iOS 27 today. Is it affected?** If it was built with Xcode 26 or earlier, the
+check does not apply to that build: in our run the same code linked against the iOS 26 SDK
+launched on the iOS 27 simulator. It applies to your next build with Xcode 27.
+
+**Does sdkbump replace testing on a device?** No. It reads files. The simulator recordings in this
+repository are from the iOS 27.0 simulator; nothing here was run on a device.
+
+**Why is a finding "handled"?** A workaround package in package.json (react-native-uiscene-bridge
+or react-native-xcode27) declares a scene at run time. The app launches, but it still has no scene
+support of its own; the report lists the package's limits and the real fix.
+
+**Does sdkbump change my project?** No. It reads it and writes only the report you ask for.
+
+## Contributing
+
+Contributions are welcome: read [CONTRIBUTING.md](CONTRIBUTING.md) and the
+[code of conduct](https://github.com/muhittincamdali/.github/blob/main/CODE_OF_CONDUCT.md) before
+opening a pull request, and report security issues as described in [SECURITY.md](SECURITY.md).
+
+## License
+
+Released under the MIT license. See [LICENSE](LICENSE).