parityguard 0.1.0-alpha.0 → 0.1.0-alpha.1

package/README.md

@@ -47,13 +47,21 @@ parityguard explain PG002                 # explain one rule
 
 | ID | What it catches | Default |
 |---|---|---|
-| PG001 | `if (Platform.OS === 'ios')` with no else and no early return. The `&&` form (`Platform.OS === 'ios' && …`) is medium confidence and needs `--strict`. | warn |
-| PG002 | `Platform.select` missing `ios`/`android` with no `default` or `native` key | error |
+| PG001 | `if (Platform.OS === 'ios')` with no else and no early return, **unless** the same function also handles the other platform (another `Platform.OS` check or `Platform.select`). The `&&` form (`Platform.OS === 'ios' && …`) is medium confidence and needs `--strict`. | warn |
+| PG002 | `Platform.select` missing `ios`/`android` with no `default` or `native` key. Style-like usage (spread, or all values are objects) is medium confidence, `--strict` only. | error |
 | PG003 | `X.ios.tsx` and `X.android.tsx` that export different names | error |
-| PG006 | Privacy-sensitive library used (camera, location, ...) with no iOS usage string | error |
-| PG007 | Same library used with no Android permission | error |
-
-PG006 and PG007 are data-driven: add libraries in `data/capabilities.json`, no code change needed.
+| PG006 | Privacy-sensitive library used with no iOS usage string, **or** a usage string that is empty | error |
+| PG007 | Library used with no Android permission, **or** `PermissionsAndroid.PERMISSIONS.X` used in code but not declared | error |
+| PG008 | Notification library used without `POST_NOTIFICATIONS` declared (Android 13+). A missing runtime request is medium confidence (`--strict`) | warn |
+| PG009 | `<Modal>` without `onRequestClose`, or a `BackHandler.addEventListener` subscription that is discarded and never removed | warn |
+| PG010 | Single-platform package (e.g. `expo-apple-authentication`) imported with no platform guard, or in the wrong `.ios`/`.android` file | warn |
+
+PG004 and PG005 (iOS-only props, shadow without elevation) are reserved for a later release.
+
+Rules are data-driven where possible, so adding coverage needs no code change:
+- `data/capabilities.json`: libraries and the iOS keys / Android permissions they need (PG006, PG007)
+- `data/notifications.json`: notification libraries and request calls (PG008)
+- `data/platform-support.json`: single-platform packages (PG010). Seeded from package docs, so verify entries against current docs and send corrections.
 Config plugins (Expo) are matched by name only, so a plugin is assumed to declare what it should.
 
 Run `parityguard explain <ID>` for details.
@@ -99,7 +107,7 @@ Copy `examples/parityguard-workflow.yml` into your app repo as `.github/workflow
 
 Action inputs: `path`, `strict`, `version`, `sarif-file`, `upload-sarif`, `fail-on-error`.
 
-Before using it: publish the package to npm (the Action runs it through `npx`), replace `mechazod` in the workflow, and confirm the pinned versions of `actions/setup-node` and `github/codeql-action` are current. The Action has not yet been run on GitHub.
+Before using it: publish the package to npm (the Action runs it through `npx`), replace `YOUR_ORG` in the workflow, and confirm the pinned versions of `actions/setup-node` and `github/codeql-action` are current. The Action has not yet been run on GitHub.
 
 ## Known limitations
 
@@ -107,6 +115,8 @@ Before using it: publish the package to npm (the Action runs it through `npx`),
 - Apps nested inside a larger repo are not auto-discovered yet. Point the CLI at the app folder.
 - Only `Platform.OS` comparisons against `'ios'` and `'android'` are analyzed. `web` is ignored.
 - `ios/` and `android/` source folders are not scanned for JS/TS.
+- PG010 treats a file as guarded if it mentions `Platform`, `isIOS` or `isAndroid` anywhere; it cannot follow guards in other files.
+- PG008 does not read `targetSdkVersion`; it assumes you target Android 13+.
 - Not yet validated on a large corpus, so the false-positive rate is unknown.
 
 ## Measuring false positives (corpus)
@@ -139,6 +149,16 @@ scripts/            corpus tooling
 3. Add a violation to `fixtures/bad-app`, keep `fixtures/good-app` clean, and update `test/engine.test.ts`.
 4. Prefer fewer, high-confidence rules. Medium-confidence rules stay hidden unless `--strict`.
 
+## Releasing
+
+```bash
+npm run bump:alpha      # also: bump:patch | bump:minor | bump:major (needs a clean git tree)
+npm run publish:alpha   # or publish:latest for stable
+npm run release:alpha   # bump + publish alpha + push commit and tag
+```
+
+See `docs/ADOPTION_AND_CONTRIBUTING.md` for the full release process.
+
 ## Troubleshooting
 
 - `tsc` or `vitest` not found: run `npm install` first.
@@ -148,3 +168,4 @@ scripts/            corpus tooling
 ## License
 
 MIT. Add a `LICENSE` file before publishing.
+x

package/data/capabilities.json

@@ -1,5 +1,5 @@
 {
-  "dataVersion": "2026.11.0",
+  "dataVersion": "2026.11.1",
   "capabilities": [
     { "id": "camera", "imports": ["expo-camera", "react-native-vision-camera", "react-native-camera"],
       "iosKeys": ["NSCameraUsageDescription"], "androidPermissions": ["android.permission.CAMERA"],
@@ -17,6 +17,21 @@
     { "id": "photos", "imports": ["expo-image-picker", "expo-media-library", "@react-native-camera-roll/camera-roll"],
       "iosKeys": ["NSPhotoLibraryUsageDescription"],
       "androidPermissions": ["android.permission.READ_MEDIA_IMAGES", "android.permission.READ_EXTERNAL_STORAGE"],
-      "expoPlugins": ["expo-image-picker", "expo-media-library"] }
+      "expoPlugins": ["expo-image-picker", "expo-media-library"] },
+    { "id": "biometrics", "imports": ["expo-local-authentication"],
+      "iosKeys": ["NSFaceIDUsageDescription"],
+      "androidPermissions": ["android.permission.USE_BIOMETRIC", "android.permission.USE_FINGERPRINT"],
+      "expoPlugins": ["expo-local-authentication"] },
+    { "id": "bluetooth", "imports": ["react-native-ble-plx", "react-native-ble-manager"],
+      "iosKeys": ["NSBluetoothAlwaysUsageDescription"],
+      "androidPermissions": ["android.permission.BLUETOOTH_SCAN", "android.permission.BLUETOOTH_CONNECT", "android.permission.BLUETOOTH"],
+      "expoPlugins": ["react-native-ble-plx"] },
+    { "id": "calendar", "imports": ["expo-calendar"],
+      "iosKeys": ["NSCalendarsUsageDescription", "NSCalendarsFullAccessUsageDescription"],
+      "androidPermissions": ["android.permission.READ_CALENDAR", "android.permission.WRITE_CALENDAR"],
+      "expoPlugins": ["expo-calendar"] },
+    { "id": "tracking", "imports": ["expo-tracking-transparency"],
+      "iosKeys": ["NSUserTrackingUsageDescription"], "androidPermissions": [],
+      "expoPlugins": ["expo-tracking-transparency"] }
   ]
 }

package/data/notifications.json

@@ -0,0 +1,6 @@
+{
+  "dataVersion": "2026.11.1",
+  "imports": ["expo-notifications", "@notifee/react-native", "react-native-push-notification", "@react-native-firebase/messaging"],
+  "expoPlugins": ["expo-notifications"],
+  "requestCalls": ["requestPermissionsAsync", "requestPermission", "requestPermissions"]
+}

package/data/platform-support.json

@@ -0,0 +1,13 @@
+{
+  "dataVersion": "2026.11.1",
+  "_note": "Seeded from package documentation; verify each entry against the package's current docs before relying on it. PRs welcome.",
+  "packages": [
+    { "package": "expo-apple-authentication", "platform": "ios" },
+    { "package": "react-native-health", "platform": "ios" },
+    { "package": "@react-native-community/push-notification-ios", "platform": "ios" },
+    { "package": "expo-intent-launcher", "platform": "android" },
+    { "package": "expo-navigation-bar", "platform": "android" },
+    { "package": "react-native-health-connect", "platform": "android" },
+    { "package": "react-native-send-intent", "platform": "android" }
+  ]
+}

package/dist/cli.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import fs from "node:fs";
+import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 import path from "node:path";
 import { loadConfig } from "./config.js";
@@ -12,6 +14,7 @@ Usage:
   parityguard check [path] --update-baseline
   parityguard rules
   parityguard explain <RULE_ID>
+  parityguard --version
 
 Exit codes: 0 clean (or warnings only), 1 errors found, 2 usage/internal error.`;
 async function main() {
@@ -23,9 +26,15 @@ async function main() {
             "update-baseline": { type: "boolean", default: false },
             "no-baseline": { type: "boolean", default: false },
             config: { type: "string" },
+            version: { type: "boolean", short: "v", default: false },
             help: { type: "boolean", short: "h", default: false },
         },
     });
+    if (values.version) {
+        const pkg = JSON.parse(fs.readFileSync(fileURLToPath(new URL("../package.json", import.meta.url)), "utf8"));
+        console.log(pkg.version);
+        return 0;
+    }
     const [cmd, arg] = positionals;
     if (values.help || !cmd) {
         console.log(HELP);

package/dist/data.d.ts

@@ -0,0 +1,2 @@
+/** Loads a versioned JSON data file shipped in /data (works from src/ and dist/). */
+export declare function loadData<T>(name: string): T;

package/dist/data.js

@@ -0,0 +1,8 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const here = path.dirname(fileURLToPath(import.meta.url));
+/** Loads a versioned JSON data file shipped in /data (works from src/ and dist/). */
+export function loadData(name) {
+    return JSON.parse(fs.readFileSync(path.resolve(here, "../data", name), "utf8"));
+}

package/dist/engine.js

@@ -26,15 +26,22 @@ export function analyze(root, opts = {}) {
         if (override === "off")
             continue;
         const rule = override ? { ...base, severity: override } : base;
+        const seen = new Map();
         const report = (r) => {
-            const text = fs.readFileSync(r.file, "utf8").split(/\r?\n/)[r.line - 1]?.trim() ?? "";
+            const source = fs.readFileSync(r.file, "utf8");
+            const text = source.split(/\r?\n/)[r.line - 1]?.trim() ?? "";
             const rel = path.relative(root, r.file).split(path.sep).join("/");
             const confidence = r.confidence ?? rule.confidence;
-            if (isSuppressed(fs.readFileSync(r.file, "utf8"), r.line, rule.id)) {
+            // Identical source lines in one file get an occurrence index, so baselines can tell them apart.
+            // Counted before any filtering so the index doesn't depend on flags like --strict.
+            const key = `${rule.id}|${rel}|${r.anchor ?? text}`;
+            const nth = seen.get(key) ?? 0;
+            seen.set(key, nth + 1);
+            const fingerprint = crypto.createHash("sha1").update(nth === 0 ? key : `${key}#${nth}`).digest("hex").slice(0, 16);
+            if (isSuppressed(source, r.line, rule.id)) {
                 suppressed++;
                 return;
             }
-            const fingerprint = crypto.createHash("sha1").update(`${rule.id}|${rel}|${r.anchor ?? text}`).digest("hex").slice(0, 16);
             if (opts.baseline?.has(fingerprint)) {
                 baselined++;
                 return;

package/dist/project.js

@@ -23,7 +23,7 @@ function readJson(p) {
 export function loadNativeConfig(root) {
     const n = {
         isExpo: false, dynamicConfig: false, hasIosConfig: false, hasAndroidConfig: false,
-        iosKeys: new Set(), androidPermissions: new Set(), expoPlugins: new Set(),
+        iosKeys: new Set(), iosEmpty: new Set(), androidPermissions: new Set(), expoPlugins: new Set(),
     };
     // Expo static config
     const appJson = readJson(path.join(root, "app.json"));
@@ -32,7 +32,11 @@ export function loadNativeConfig(root) {
         n.isExpo = true;
         n.hasIosConfig = true;
         n.hasAndroidConfig = true;
-        Object.keys(expo.ios?.infoPlist ?? {}).forEach((k) => n.iosKeys.add(k));
+        for (const [k, v] of Object.entries(expo.ios?.infoPlist ?? {})) {
+            n.iosKeys.add(k);
+            if (typeof v === "string" && v.trim() === "")
+                n.iosEmpty.add(k);
+        }
         for (const p of expo.android?.permissions ?? []) {
             n.androidPermissions.add(p.includes(".") ? p : `android.permission.${p}`);
         }
@@ -50,8 +54,11 @@ export function loadNativeConfig(root) {
             const plist = path.join(iosDir, d.name, "Info.plist");
             if (d.isDirectory() && fs.existsSync(plist)) {
                 n.hasIosConfig = true;
-                for (const m of fs.readFileSync(plist, "utf8").matchAll(/<key>([^<]+)<\/key>/g))
+                const xml = fs.readFileSync(plist, "utf8");
+                for (const m of xml.matchAll(/<key>([^<]+)<\/key>/g))
                     n.iosKeys.add(m[1]);
+                for (const m of xml.matchAll(/<key>([^<]+)<\/key>\s*<string>\s*<\/string>/g))
+                    n.iosEmpty.add(m[1]);
             }
         }
     }

package/dist/rules/helpers.d.ts

@@ -11,3 +11,9 @@ export declare const pos: (n: Node) => {
     line: number;
     column: number;
 };
+export declare function effectivePlatform(c: {
+    platform: PlatformName;
+    negated: boolean;
+}): PlatformName;
+/** Nearest enclosing function-like node, or the source file. */
+export declare function enclosingScope(n: Node): Node;

package/dist/rules/helpers.js

@@ -26,3 +26,10 @@ export const pos = (n) => {
     const { line, column } = sf.getLineAndColumnAtPos(n.getStart());
     return { file: sf.getFilePath(), line, column };
 };
+export function effectivePlatform(c) {
+    return c.negated ? (c.platform === "ios" ? "android" : "ios") : c.platform;
+}
+/** Nearest enclosing function-like node, or the source file. */
+export function enclosingScope(n) {
+    return (n.getFirstAncestor((a) => Node.isFunctionDeclaration(a) || Node.isFunctionExpression(a) || Node.isArrowFunction(a) || Node.isMethodDeclaration(a)) ?? n.getSourceFile());
+}

package/dist/rules/index.js

@@ -1,5 +1,12 @@
 import { pg001 } from "./pg001-unmatched-os-branch.js";
 import { pg002 } from "./pg002-incomplete-platform-select.js";
 import { pg003 } from "./pg003-divergent-platform-files.js";
+import { pg008 } from "./pg008-android-notification-permission.js";
+import { pg009 } from "./pg009-android-back-button.js";
+import { pg010 } from "./pg010-unsupported-platform-dependency.js";
 import { makePermissionRule } from "./permissions.js";
-export const rules = [pg001, pg002, pg003, makePermissionRule("ios"), makePermissionRule("android")];
+export const rules = [
+    pg001, pg002, pg003,
+    makePermissionRule("ios"), makePermissionRule("android"),
+    pg008, pg009, pg010,
+];

package/dist/rules/permissions.js

@@ -1,9 +1,7 @@
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-const here = path.dirname(fileURLToPath(import.meta.url));
-export const capabilityData = JSON.parse(fs.readFileSync(path.resolve(here, "../../data/capabilities.json"), "utf8"));
-function usages(ctx) {
+import { SyntaxKind } from "ts-morph";
+import { loadData } from "../data.js";
+export const capabilityData = loadData("capabilities.json");
+function libraryUsages(ctx) {
     const found = new Map();
     for (const sf of ctx.sourceFiles) {
         for (const imp of sf.getImportDeclarations()) {
@@ -18,38 +16,93 @@ function usages(ctx) {
     }
     return [...found.values()];
 }
+/** `PermissionsAndroid.PERMISSIONS.CAMERA` -> android.permission.CAMERA (first occurrence). */
+function codePermissionUsages(ctx) {
+    const found = new Map();
+    for (const sf of ctx.sourceFiles) {
+        for (const pae of sf.getDescendantsOfKind(SyntaxKind.PropertyAccessExpression)) {
+            const m = pae.getText().match(/^PermissionsAndroid\.PERMISSIONS\.([A-Z0-9_]+)$/);
+            if (!m || found.has(m[1]))
+                continue;
+            const { line, column } = sf.getLineAndColumnAtPos(pae.getStart());
+            found.set(`android.permission.${m[1]}`, { file: sf.getFilePath(), line, column });
+        }
+    }
+    return found;
+}
 export function makePermissionRule(platform) {
     const ios = platform === "ios";
     return {
         id: ios ? "PG006" : "PG007",
-        title: ios ? "Missing iOS usage description" : "Missing Android permission",
+        title: ios ? "Missing or empty iOS usage description" : "Missing Android permission",
         severity: "error",
         confidence: "high",
         explain: ios
-            ? "Using a privacy-sensitive API without the matching Info.plist usage string crashes the app on iOS and gets it rejected in review."
-            : "Using a protected API without declaring the permission means the request is silently denied on Android.",
+            ? "Using a privacy-sensitive API without a matching, non-empty Info.plist usage string crashes the app on iOS and gets it rejected in review. " +
+                "Detected from imports of known libraries (data/capabilities.json). An Expo config plugin for the library counts as declared."
+            : "Using a protected API without declaring the permission means requests are silently denied on Android. " +
+                "Detected from imports of known libraries and from `PermissionsAndroid.PERMISSIONS.X` usage in code. " +
+                "POST_NOTIFICATIONS is covered by PG008.",
         check(ctx, report) {
             const n = ctx.native;
             if (ios ? !n.hasIosConfig : !n.hasAndroidConfig)
                 return; // nothing to compare against
-            for (const u of usages(ctx)) {
-                const declared = ios
-                    ? u.cap.iosKeys.some((k) => n.iosKeys.has(k))
-                    : u.cap.androidPermissions.some((p) => n.androidPermissions.has(p));
+            const confidence = n.dynamicConfig ? "low" : "high";
+            const coveredAndroid = new Set();
+            for (const u of libraryUsages(ctx)) {
                 const viaPlugin = u.cap.expoPlugins.some((p) => n.expoPlugins.has(p));
-                if (declared || viaPlugin)
-                    continue;
-                const need = ios ? u.cap.iosKeys : u.cap.androidPermissions;
-                report({
-                    file: u.file, line: u.line, column: u.column, anchor: `${u.cap.id}:${platform}`,
-                    confidence: n.dynamicConfig ? "low" : "high",
-                    message: `\`${u.mod}\` (${u.cap.id}) is used but ${ios ? "no usage description" : "no permission"} is declared. Expected one of: ${need.join(", ")}.`,
-                    why: ios ? "iOS terminates the app when this API is used without a usage string; App Store review also rejects it."
-                        : "Android denies the permission request without a manifest declaration, so the feature fails only on Android.",
-                    fix: n.isExpo
-                        ? `Add the \`${u.cap.expoPlugins[0] ?? u.cap.id}\` config plugin, or set ${ios ? "expo.ios.infoPlist" : "expo.android.permissions"} in app.json.`
-                        : ios ? `Add ${need[0]} to ios/<App>/Info.plist.` : `Add <uses-permission android:name="${need[0]}"/> to AndroidManifest.xml.`,
-                });
+                if (ios) {
+                    const declared = u.cap.iosKeys.filter((k) => n.iosKeys.has(k));
+                    if (viaPlugin)
+                        continue;
+                    if (declared.length && declared.every((k) => n.iosEmpty.has(k))) {
+                        report({
+                            file: u.file, line: u.line, column: u.column, anchor: `${u.cap.id}:ios:empty`, confidence,
+                            message: `\`${u.mod}\` (${u.cap.id}) is used but ${declared.join(", ")} is empty.`,
+                            why: "App Store review rejects empty usage descriptions, and users see a blank reason in the permission prompt.",
+                            fix: "Write a short, specific explanation of why the app needs this access.",
+                        });
+                    }
+                    else if (!declared.length) {
+                        report({
+                            file: u.file, line: u.line, column: u.column, anchor: `${u.cap.id}:ios`, confidence,
+                            message: `\`${u.mod}\` (${u.cap.id}) is used but no usage description is declared. Expected one of: ${u.cap.iosKeys.join(", ")}.`,
+                            why: "iOS terminates the app when this API is used without a usage string; App Store review also rejects it.",
+                            fix: n.isExpo
+                                ? `Add the \`${u.cap.expoPlugins[0] ?? u.cap.id}\` config plugin, or set expo.ios.infoPlist in app.json.`
+                                : `Add ${u.cap.iosKeys[0]} to ios/<App>/Info.plist.`,
+                        });
+                    }
+                }
+                else {
+                    if (!u.cap.androidPermissions.length)
+                        continue; // no Android equivalent
+                    if (viaPlugin || u.cap.androidPermissions.some((p) => n.androidPermissions.has(p))) {
+                        u.cap.androidPermissions.forEach((p) => coveredAndroid.add(p));
+                        continue;
+                    }
+                    u.cap.androidPermissions.forEach((p) => coveredAndroid.add(p));
+                    report({
+                        file: u.file, line: u.line, column: u.column, anchor: `${u.cap.id}:android`, confidence,
+                        message: `\`${u.mod}\` (${u.cap.id}) is used but no permission is declared. Expected one of: ${u.cap.androidPermissions.join(", ")}.`,
+                        why: "Android denies the permission request without a manifest declaration, so the feature fails only on Android.",
+                        fix: n.isExpo
+                            ? `Add the \`${u.cap.expoPlugins[0] ?? u.cap.id}\` config plugin, or set expo.android.permissions in app.json.`
+                            : `Add <uses-permission android:name="${u.cap.androidPermissions[0]}"/> to AndroidManifest.xml.`,
+                    });
+                }
+            }
+            if (!ios) {
+                for (const [perm, loc] of codePermissionUsages(ctx)) {
+                    if (perm === "android.permission.POST_NOTIFICATIONS" || coveredAndroid.has(perm) || n.androidPermissions.has(perm))
+                        continue;
+                    report({
+                        ...loc, anchor: `perm:${perm}`, confidence,
+                        message: `Code requests ${perm} but it is not declared.`,
+                        why: "PermissionsAndroid.request resolves as denied when the permission is missing from the manifest.",
+                        fix: n.isExpo ? `Add "${perm.split(".").pop()}" to expo.android.permissions.` : `Add <uses-permission android:name="${perm}"/> to AndroidManifest.xml.`,
+                    });
+                }
             }
         },
     };

package/dist/rules/pg001-unmatched-os-branch.js

@@ -1,23 +1,41 @@
 import { Node, SyntaxKind } from "ts-morph";
-import { asPlatformCheck, endsWithExit, pos } from "./helpers.js";
+import { asPlatformCheck, effectivePlatform, endsWithExit, enclosingScope, pos } from "./helpers.js";
+/** True when the enclosing function also contains a check/select for the opposite platform. */
+function handlesOtherPlatform(self, chk) {
+    const scope = enclosingScope(self);
+    const mine = effectivePlatform(chk);
+    if (scope.getDescendantsOfKind(SyntaxKind.CallExpression).some((c) => c.getExpression().getText() === "Platform.select"))
+        return true;
+    return scope.getDescendantsOfKind(SyntaxKind.BinaryExpression).some((b) => {
+        if (b === self)
+            return false;
+        const other = asPlatformCheck(b);
+        return !!other && effectivePlatform(other) !== mine;
+    });
+}
 export const pg001 = {
     id: "PG001",
     title: "Platform.OS branch has no counterpart",
     severity: "warn",
     confidence: "high",
     explain: "An `if (Platform.OS === 'ios')` with no else (and no early return) means the other platform silently skips that logic. " +
-        "`Platform.OS === 'x' && <JSX/>` is reported at medium confidence because it is often intentional (shown only with --strict).",
+        "`Platform.OS === 'x' && <JSX/>` is reported at medium confidence because it is often intentional (shown only with --strict). " +
+        "Not reported when the same function also handles the other platform (another Platform.OS check, or Platform.select), since the platforms are then handled side by side.",
     check(ctx, report) {
         for (const sf of ctx.sourceFiles) {
             for (const ifs of sf.getDescendantsOfKind(SyntaxKind.IfStatement)) {
                 const chk = asPlatformCheck(ifs.getExpression());
                 if (!chk || ifs.getElseStatement() || endsWithExit(ifs.getThenStatement()))
                     continue;
-                const other = chk.platform === "ios" ? "android" : "ios";
+                if (handlesOtherPlatform(ifs.getExpression(), chk))
+                    continue;
+                const branch = effectivePlatform(chk);
+                const other = branch === "ios" ? "android" : "ios";
+                const cond = `Platform.OS ${chk.negated ? "!==" : "==="} '${chk.platform}'`;
                 report({
                     ...pos(ifs),
-                    message: `Branch for ${chk.negated ? "non-" : ""}${chk.platform} has no ${other} counterpart.`,
-                    why: `On ${chk.negated ? chk.platform : other}, this logic is skipped entirely with no fallback.`,
+                    message: `\`${cond}\` branch runs on ${branch} only; nothing handles ${other}.`,
+                    why: `On ${other}, this logic is skipped entirely with no fallback.`,
                     fix: `Add an else branch, or add \`// parity-ignore PG001: <reason>\` if the difference is intentional.`,
                 });
             }

package/dist/rules/pg002-incomplete-platform-select.js

@@ -5,7 +5,8 @@ export const pg002 = {
     title: "Platform.select is missing a platform",
     severity: "error",
     confidence: "high",
-    explain: "`Platform.select({ ios: … })` returns `undefined` on Android unless `android`, `native`, or `default` is provided.",
+    explain: "`Platform.select({ ios: … })` returns `undefined` on Android unless `android`, `native`, or `default` is provided. " +
+        "When the result is spread into an object or every value is an object (typical style overrides), `undefined` is usually harmless, so those cases are medium confidence (shown with --strict).",
     check(ctx, report) {
         for (const sf of ctx.sourceFiles) {
             for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
@@ -22,8 +23,12 @@ export const pg002 = {
                 const missing = ["ios", "android"].filter((k) => !keys.has(k));
                 if (missing.length === 0)
                     continue;
+                const parent = call.getParent();
+                const styleLike = Node.isSpreadAssignment(parent) || Node.isSpreadElement(parent) ||
+                    arg.getProperties().every((p) => Node.isPropertyAssignment(p) && Node.isObjectLiteralExpression(p.getInitializer()));
                 report({
                     ...pos(call),
+                    confidence: styleLike ? "medium" : undefined,
                     message: `Platform.select is missing: ${missing.join(", ")}.`,
                     why: `On ${missing.join(" and ")} this expression evaluates to \`undefined\` at runtime.`,
                     fix: "Add the missing key, or add a `default` value.",

package/dist/rules/pg008-android-notification-permission.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const pg008: Rule;

package/dist/rules/pg008-android-notification-permission.js

@@ -0,0 +1,51 @@
+import { SyntaxKind } from "ts-morph";
+import { loadData } from "../data.js";
+const data = loadData("notifications.json");
+export const pg008 = {
+    id: "PG008",
+    title: "Android 13+ notification permission not handled",
+    severity: "warn",
+    confidence: "high",
+    explain: "On Android 13 (API 33)+, apps targeting API 33+ must declare POST_NOTIFICATIONS and request it at runtime; otherwise notifications are silently dropped. " +
+        "iOS always prompts, so this only breaks on Android. The runtime-request check is medium confidence (shown with --strict) because the request may live behind a wrapper. " +
+        "An Expo `expo-notifications` plugin is assumed to declare the permission.",
+    check(ctx, report) {
+        const n = ctx.native;
+        if (!n.hasAndroidConfig)
+            return;
+        let loc;
+        for (const sf of ctx.sourceFiles) {
+            for (const imp of sf.getImportDeclarations()) {
+                const mod = imp.getModuleSpecifierValue();
+                if (loc || !data.imports.some((i) => mod === i || mod.startsWith(i + "/")))
+                    continue;
+                const { line, column } = sf.getLineAndColumnAtPos(imp.getStart());
+                loc = { file: sf.getFilePath(), line, column, mod };
+            }
+        }
+        if (!loc)
+            return;
+        const declared = n.androidPermissions.has("android.permission.POST_NOTIFICATIONS") || data.expoPlugins.some((p) => n.expoPlugins.has(p));
+        if (!declared) {
+            report({
+                ...loc, anchor: "notif:declare", confidence: n.dynamicConfig ? "low" : "high",
+                message: `\`${loc.mod}\` is used but android.permission.POST_NOTIFICATIONS is not declared.`,
+                why: "On Android 13+ notifications are blocked until the permission is declared and granted. iOS prompts automatically, so this only fails on Android.",
+                fix: n.isExpo ? "Add the `expo-notifications` plugin or \"POST_NOTIFICATIONS\" to expo.android.permissions." : `Add <uses-permission android:name="android.permission.POST_NOTIFICATIONS"/> to AndroidManifest.xml.`,
+            });
+        }
+        const hasRequest = ctx.sourceFiles.some((sf) => sf.getDescendantsOfKind(SyntaxKind.CallExpression).some((c) => {
+            const text = c.getExpression().getText();
+            return data.requestCalls.includes(text.split(".").pop() ?? "") ||
+                (text.endsWith("PermissionsAndroid.request") && c.getText().includes("POST_NOTIFICATIONS"));
+        }));
+        if (!hasRequest) {
+            report({
+                ...loc, anchor: "notif:request", confidence: "medium",
+                message: "No runtime notification-permission request found anywhere in the project.",
+                why: "Declaring the permission is not enough on Android 13+; the user must be asked at runtime.",
+                fix: "Call your library's permission request (e.g. requestPermissionsAsync) or PermissionsAndroid.request with POST_NOTIFICATIONS before scheduling notifications.",
+            });
+        }
+    },
+};

package/dist/rules/pg009-android-back-button.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const pg009: Rule;

package/dist/rules/pg009-android-back-button.js

@@ -0,0 +1,50 @@
+import { Node, SyntaxKind } from "ts-morph";
+import { pos } from "./helpers.js";
+export const pg009 = {
+    id: "PG009",
+    title: "Android hardware back button not handled",
+    severity: "warn",
+    confidence: "high",
+    explain: "Two Android-only traps: (1) react-native `Modal` without `onRequestClose` ignores the hardware back button and RN requires the prop on Android; " +
+        "(2) `BackHandler.addEventListener(...)` whose subscription is discarded can never be removed, so the handler leaks and keeps hijacking back presses. iOS has no back button, so neither shows up there.",
+    check(ctx, report) {
+        for (const sf of ctx.sourceFiles) {
+            const modalLocal = sf.getImportDeclarations()
+                .filter((i) => i.getModuleSpecifierValue() === "react-native")
+                .flatMap((i) => i.getNamedImports())
+                .find((s) => s.getName() === "Modal");
+            if (modalLocal) {
+                const local = modalLocal.getAliasNode()?.getText() ?? "Modal";
+                const els = [...sf.getDescendantsOfKind(SyntaxKind.JsxOpeningElement), ...sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement)];
+                for (const el of els) {
+                    if (el.getTagNameNode().getText() !== local)
+                        continue;
+                    const attrs = el.getAttributes();
+                    if (attrs.some((a) => Node.isJsxSpreadAttribute(a)))
+                        continue; // cannot know
+                    if (attrs.some((a) => Node.isJsxAttribute(a) && a.getNameNode().getText() === "onRequestClose"))
+                        continue;
+                    report({
+                        ...pos(el),
+                        message: "`<Modal>` has no `onRequestClose`.",
+                        why: "On Android the hardware back button cannot dismiss this modal, and React Native requires the prop on Android.",
+                        fix: "Add `onRequestClose={() => setVisible(false)}` (or your close handler).",
+                    });
+                }
+            }
+            if (sf.getFullText().includes("BackHandler.removeEventListener"))
+                continue; // legacy cleanup pattern present
+            for (const st of sf.getDescendantsOfKind(SyntaxKind.ExpressionStatement)) {
+                const e = st.getExpression();
+                if (Node.isCallExpression(e) && e.getExpression().getText() === "BackHandler.addEventListener") {
+                    report({
+                        ...pos(st),
+                        message: "`BackHandler.addEventListener` subscription is discarded, so it is never removed.",
+                        why: "The handler keeps intercepting the back button after the screen unmounts, trapping the user or skipping navigation.",
+                        fix: "Store the result and call `.remove()` in the effect cleanup: `const sub = BackHandler.addEventListener(...); return () => sub.remove();`",
+                    });
+                }
+            }
+        }
+    },
+};

package/dist/rules/pg010-unsupported-platform-dependency.d.ts

@@ -0,0 +1,2 @@
+import type { Rule } from "../types.js";
+export declare const pg010: Rule;

package/dist/rules/pg010-unsupported-platform-dependency.js

@@ -0,0 +1,45 @@
+import { loadData } from "../data.js";
+const data = loadData("platform-support.json");
+const GUARD = /\bPlatform\b|\bis(?:IOS|Ios|Android)\b|\bIS_(?:IOS|ANDROID)\b/;
+export const pg010 = {
+    id: "PG010",
+    title: "Single-platform dependency used without a platform guard",
+    severity: "warn",
+    confidence: "high",
+    explain: "Some packages only ship a native module for one platform (see data/platform-support.json). Importing them from shared code with no guard " +
+        "means the other platform hits a missing native module at runtime. A file is considered guarded if it references `Platform`/`isIOS`/`isAndroid`, " +
+        "or is a matching `.ios`/`.android` file. Data is seeded from package docs and should be verified.",
+    check(ctx, report) {
+        for (const sf of ctx.sourceFiles) {
+            const fileSuffix = sf.getFilePath().match(/\.(ios|android)\.[jt]sx?$/)?.[1];
+            const guarded = GUARD.test(sf.getFullText());
+            for (const imp of sf.getImportDeclarations()) {
+                const mod = imp.getModuleSpecifierValue();
+                const entry = data.packages.find((p) => mod === p.package || mod.startsWith(p.package + "/"));
+                if (!entry)
+                    continue;
+                const other = entry.platform === "ios" ? "Android" : "iOS";
+                const { line, column } = sf.getLineAndColumnAtPos(imp.getStart());
+                const base = { file: sf.getFilePath(), line, column, anchor: `${mod}:${fileSuffix ?? "shared"}` };
+                if (fileSuffix) {
+                    if (fileSuffix === entry.platform)
+                        continue;
+                    report({
+                        ...base,
+                        message: `\`${mod}\` supports ${entry.platform === "ios" ? "iOS" : "Android"} only but is imported in a .${fileSuffix} file.`,
+                        why: `The ${other} build has no native module for this package.`,
+                        fix: `Move the import to the .${entry.platform} file and give ${other} its own implementation.`,
+                    });
+                }
+                else if (!guarded) {
+                    report({
+                        ...base,
+                        message: `\`${mod}\` supports ${entry.platform === "ios" ? "iOS" : "Android"} only but is imported with no platform guard.`,
+                        why: `On ${other} the native module does not exist, so calls throw or silently do nothing.`,
+                        fix: `Guard usage with Platform.OS === '${entry.platform}', or split into .${entry.platform}/.${entry.platform === "ios" ? "android" : "ios"} files.`,
+                    });
+                }
+            }
+        }
+    },
+};

package/dist/types.d.ts

@@ -31,6 +31,8 @@ export interface NativeConfig {
     hasIosConfig: boolean;
     hasAndroidConfig: boolean;
     iosKeys: Set<string>;
+    /** iOS usage keys that are declared but have an empty value. */
+    iosEmpty: Set<string>;
     androidPermissions: Set<string>;
     expoPlugins: Set<string>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "parityguard",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "description": "Catch iOS/Android drift in React Native TypeScript projects before it reaches a device.",
   "license": "MIT",
   "type": "module",
@@ -19,7 +19,15 @@
     "build": "tsc -p tsconfig.json",
     "test": "vitest run",
     "check:fixtures": "node dist/cli.js check fixtures/bad-app",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm test",
+    "preversion": "npm test",
+    "bump:alpha": "npm version prerelease --preid=alpha",
+    "bump:patch": "npm version patch",
+    "bump:minor": "npm version minor",
+    "bump:major": "npm version major",
+    "publish:alpha": "npm publish --tag alpha",
+    "publish:latest": "npm publish --tag latest",
+    "release:alpha": "npm run bump:alpha && npm run publish:alpha && git push --follow-tags"
   },
   "dependencies": {
     "ts-morph": "^28.0.0"
@@ -31,8 +39,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.org/",
-    "tag": "alpha"
+    "registry": "https://registry.npmjs.org/"
   },
   "keywords": [
     "react-native",
@@ -42,5 +49,8 @@
     "cross-platform",
     "typescript",
     "expo"
-  ]
+  ],
+  "overrides": {
+    "minimatch": "^11.0.7"
+  }
 }