parityguard 0.0.0-stage → 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ParityGuard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+# ParityGuard
 
-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.
+Catch iOS/Android drift in React Native + TypeScript projects before it reaches a device.
+
+> **Status: v0.1 alpha.** Five rules, tested on small fixtures and two clean real-world repos. Expect rough edges, and please report false positives.
+
+ESLint tells you your code is wrong. ParityGuard tells you your code is right on one platform and wrong on the other.
+
+## Requirements
+
+| Use | Node |
+|---|---|
+| Developing ParityGuard (build + tests) | **22.12+** (Vitest 5 requirement) |
+| Running the built CLI | 20.19+ (only tested on Node 22) |
+
+Works on macOS, Linux and Windows. No network access is needed during a run.
+
+## Quick start
+
+```bash
+git clone <your-repo-url> parityguard && cd parityguard
+npm install
+npm run build
+npm test
+
+node dist/cli.js check <path-to-your-rn-app>
+```
+
+Once published to npm this becomes `npx parityguard check`.
+
+## Commands
+
+```bash
+parityguard check [path]                  # analyze a project (default: current dir)
+parityguard check [path] --strict         # include medium/low-confidence findings
+parityguard check [path] --format sarif   # terminal (default) | json | sarif
+parityguard check [path] --update-baseline  # record existing findings; only NEW drift fails later
+parityguard check [path] --no-baseline    # ignore the baseline file
+parityguard check [path] --config <file>  # explicit config file
+parityguard rules                         # list rules
+parityguard explain PG002                 # explain one rule
+```
+
+**Exit codes:** `0` clean or warnings only, `1` errors found, `2` usage/internal error.
+
+## Rules
+
+| ID | What it catches | Default |
+|---|---|---|
+| 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 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.
+
+## Handling intentional differences
+
+Suppress a finding with a comment on the same line or the line above. Always give a reason:
+
+```ts
+// parity-ignore PG001: Android uses the system picker
+if (Platform.OS === 'ios') { showNativePicker(); }
+```
+
+Omit the rule ID to suppress all rules on that line.
+
+## Adopting on an existing app (baseline)
+
+```bash
+parityguard check . --update-baseline   # writes parityguard.baseline.json
+```
+
+Commit the baseline file. From then on only findings that are not in it are reported. Entries are matched by rule, file and source text, so they survive unrelated line shifts.
+
+## Configuration
+
+Create `parityguard.config.json` (or `.mjs` / `.js`) in the project root:
+
+```json
+{
+  "rules": { "PG001": "warn", "PG003": "off" },
+  "exclude": ["src/legacy/**"]
+}
+```
+
+- `rules`: set a rule to `error`, `warn`, `info` or `off`.
+- `exclude`: globs relative to the project root.
+
+See `examples/parityguard.config.json`.
+
+## GitHub Action
+
+Copy `examples/parityguard-workflow.yml` into your app repo as `.github/workflows/parityguard.yml`. It runs the check, uploads SARIF to GitHub code scanning, and fails the job on errors.
+
+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 `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
+
+- Dynamic `app.config.ts/js` cannot be evaluated, so permission findings there are low confidence (hidden without `--strict`).
+- 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)
+
+1. List repos in `corpus/repos.txt` (`owner/name` or `owner/name:subdir`).
+2. `./scripts/corpus.sh` clones them and writes `corpus/results.csv` (needs bash and git; on Windows use WSL or Git Bash).
+3. Label each row `TP` or `FP` in the last column.
+4. `node scripts/fp-rate.mjs` prints the false-positive rate per rule. Target: under 5% for default-on rules.
+
+## Project layout
+
+```
+src/
+  cli.ts            command-line entry
+  engine.ts         runs rules, applies ignores, baseline, confidence
+  project.ts        loads source files and Expo/bare native config
+  config.ts         config file loading and validation
+  reporters.ts      terminal, JSON, SARIF output
+  rules/            one file per rule, plus shared helpers
+data/               versioned JSON data (capabilities)
+fixtures/           bad-app and good-app used by tests
+test/               Vitest tests
+scripts/            corpus tooling
+```
+
+## Adding a rule
+
+1. Create `src/rules/pgXXX-name.ts` exporting a `Rule` (`id`, `title`, `severity`, `confidence`, `explain`, `check`).
+2. Register it in `src/rules/index.ts`.
+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.
+- Tests fail on startup: check `node -v` (need 22.12+ for development).
+- Nothing found in an Expo project using `app.config.ts`: expected, see limitations.
+
+## License
+
+MIT. Add a `LICENSE` file before publishing.
+x

package/data/capabilities.json

@@ -0,0 +1,37 @@
+{
+  "dataVersion": "2026.11.1",
+  "capabilities": [
+    { "id": "camera", "imports": ["expo-camera", "react-native-vision-camera", "react-native-camera"],
+      "iosKeys": ["NSCameraUsageDescription"], "androidPermissions": ["android.permission.CAMERA"],
+      "expoPlugins": ["expo-camera", "react-native-vision-camera"] },
+    { "id": "location", "imports": ["expo-location", "react-native-geolocation-service", "@react-native-community/geolocation"],
+      "iosKeys": ["NSLocationWhenInUseUsageDescription", "NSLocationAlwaysAndWhenInUseUsageDescription"],
+      "androidPermissions": ["android.permission.ACCESS_FINE_LOCATION", "android.permission.ACCESS_COARSE_LOCATION"],
+      "expoPlugins": ["expo-location"] },
+    { "id": "microphone", "imports": ["expo-av", "react-native-audio-recorder-player"],
+      "iosKeys": ["NSMicrophoneUsageDescription"], "androidPermissions": ["android.permission.RECORD_AUDIO"],
+      "expoPlugins": ["expo-av", "expo-audio"] },
+    { "id": "contacts", "imports": ["expo-contacts", "react-native-contacts"],
+      "iosKeys": ["NSContactsUsageDescription"], "androidPermissions": ["android.permission.READ_CONTACTS"],
+      "expoPlugins": ["expo-contacts"] },
+    { "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"] },
+    { "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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/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";
+import { analyze, loadBaseline, writeBaseline } from "./engine.js";
+import { json, sarif, terminal } from "./reporters.js";
+import { rules } from "./rules/index.js";
+const HELP = `parityguard — catch iOS/Android drift before it reaches a device
+
+Usage:
+  parityguard check [path] [--format terminal|json|sarif] [--strict] [--no-baseline] [--config file]
+  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() {
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            format: { type: "string", default: "terminal" },
+            strict: { type: "boolean", default: false },
+            "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);
+        return cmd ? 0 : 2;
+    }
+    if (cmd === "rules") {
+        rules.forEach((r) => console.log(`${r.id}  ${r.severity.padEnd(5)}  ${r.title}`));
+        return 0;
+    }
+    if (cmd === "explain") {
+        const r = rules.find((x) => x.id === arg?.toUpperCase());
+        if (!r) {
+            console.error(`Unknown rule: ${arg}`);
+            return 2;
+        }
+        console.log(`${r.id} — ${r.title}\nDefault severity: ${r.severity}, confidence: ${r.confidence}\n\n${r.explain}`);
+        return 0;
+    }
+    if (cmd !== "check") {
+        console.error(`Unknown command: ${cmd}\n\n${HELP}`);
+        return 2;
+    }
+    const root = path.resolve(arg ?? ".");
+    const baseline = values["no-baseline"] || values["update-baseline"] ? undefined : loadBaseline(root);
+    const config = await loadConfig(root, values.config);
+    const result = analyze(root, { strict: values.strict, baseline, config });
+    if (values["update-baseline"]) {
+        writeBaseline(root, result.findings);
+        console.log(`Baseline written with ${result.findings.length} finding(s). Only new drift will fail from now on.`);
+        return 0;
+    }
+    const out = values.format === "json" ? json(result) : values.format === "sarif" ? sarif(result) : terminal(result);
+    console.log(out);
+    return result.findings.some((f) => f.severity === "error") ? 1 : 0;
+}
+main().then((c) => { process.exitCode = c; }, (e) => { console.error(e instanceof Error ? e.message : e); process.exitCode = 2; });

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+import type { Severity } from "./types.js";
+export interface Config {
+    /** Override severity per rule, or turn it off. */
+    rules?: Record<string, Severity | "off">;
+    /** Globs (relative to project root) to skip, e.g. "src/legacy/**". */
+    exclude?: string[];
+}
+export declare function loadConfig(root: string, explicit?: string): Promise<Config>;

package/dist/config.js

@@ -0,0 +1,23 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+const NAMES = ["parityguard.config.json", "parityguard.config.mjs", "parityguard.config.js"];
+export async function loadConfig(root, explicit) {
+    const file = explicit ? path.resolve(explicit) : NAMES.map((n) => path.join(root, n)).find((p) => fs.existsSync(p));
+    if (!file)
+        return {};
+    const cfg = file.endsWith(".json")
+        ? JSON.parse(fs.readFileSync(file, "utf8"))
+        : (await import(pathToFileURL(file).href)).default;
+    validate(cfg, file);
+    return cfg;
+}
+function validate(cfg, file) {
+    const ok = new Set(["error", "warn", "info", "off"]);
+    for (const [id, sev] of Object.entries(cfg.rules ?? {})) {
+        if (!ok.has(sev))
+            throw new Error(`${file}: rule ${id} has invalid severity "${sev}" (use error|warn|info|off)`);
+    }
+    if (cfg.exclude && !Array.isArray(cfg.exclude))
+        throw new Error(`${file}: "exclude" must be an array of globs`);
+}

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.d.ts

@@ -0,0 +1,17 @@
+import type { Config } from "./config.js";
+import type { Finding } from "./types.js";
+export interface AnalyzeOptions {
+    strict?: boolean;
+    baseline?: Set<string>;
+    config?: Config;
+}
+export interface AnalyzeResult {
+    findings: Finding[];
+    suppressed: number;
+    baselined: number;
+    hidden: number;
+}
+export declare function analyze(root: string, opts?: AnalyzeOptions): AnalyzeResult;
+export declare const BASELINE_FILE = "parityguard.baseline.json";
+export declare function loadBaseline(root: string): Set<string> | undefined;
+export declare function writeBaseline(root: string, findings: Finding[]): void;

package/dist/engine.js

@@ -0,0 +1,73 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { loadProject } from "./project.js";
+import { rules } from "./rules/index.js";
+const IGNORE_RE = /parity-ignore(?:\s+([A-Z0-9, ]+?))?(?:\s*:\s*(.*))?\s*(?:\*\/)?\s*$/;
+function isSuppressed(text, line, ruleId) {
+    const lines = text.split(/\r?\n/);
+    for (const idx of [line - 1, line - 2]) { // same line, or the line above
+        const m = lines[idx]?.match(IGNORE_RE);
+        if (!m || !/(\/\/|\/\*)\s*parity-ignore/.test(lines[idx]))
+            continue;
+        const ids = m[1]?.split(/[,\s]+/).filter(Boolean);
+        if (!ids || ids.includes(ruleId))
+            return true;
+    }
+    return false;
+}
+export function analyze(root, opts = {}) {
+    root = path.resolve(root);
+    const ctx = loadProject(root, opts.config?.exclude);
+    const findings = [];
+    let suppressed = 0, baselined = 0, hidden = 0;
+    for (const base of rules) {
+        const override = opts.config?.rules?.[base.id];
+        if (override === "off")
+            continue;
+        const rule = override ? { ...base, severity: override } : base;
+        const seen = new Map();
+        const report = (r) => {
+            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;
+            // 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;
+            }
+            if (opts.baseline?.has(fingerprint)) {
+                baselined++;
+                return;
+            }
+            if (confidence !== "high" && !opts.strict) {
+                hidden++;
+                return;
+            }
+            findings.push({
+                ruleId: rule.id, severity: rule.severity, confidence, message: r.message, why: r.why, fix: r.fix,
+                file: rel, line: r.line, column: r.column, fingerprint,
+            });
+        };
+        rule.check(ctx, report);
+    }
+    findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+    return { findings, suppressed, baselined, hidden };
+}
+export const BASELINE_FILE = "parityguard.baseline.json";
+export function loadBaseline(root) {
+    const p = path.join(root, BASELINE_FILE);
+    if (!fs.existsSync(p))
+        return undefined;
+    return new Set(JSON.parse(fs.readFileSync(p, "utf8")).fingerprints);
+}
+export function writeBaseline(root, findings) {
+    const fingerprints = [...new Set(findings.map((f) => f.fingerprint))].sort();
+    fs.writeFileSync(path.join(root, BASELINE_FILE), JSON.stringify({ version: 1, fingerprints }, null, 2) + "\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { analyze, loadBaseline, writeBaseline } from "./engine.js";
+export type { Finding, Rule } from "./types.js";
+export { rules } from "./rules/index.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { analyze, loadBaseline, writeBaseline } from "./engine.js";
+export { rules } from "./rules/index.js";

package/dist/project.d.ts

@@ -0,0 +1,3 @@
+import type { NativeConfig, ProjectContext } from "./types.js";
+export declare function loadProject(root: string, exclude?: string[]): ProjectContext;
+export declare function loadNativeConfig(root: string): NativeConfig;

package/dist/project.js

@@ -0,0 +1,74 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Project } from "ts-morph";
+const IGNORE = ["node_modules", "dist", "build", "Pods", ".expo", "coverage", "ios", "android"];
+export function loadProject(root, exclude = []) {
+    const project = new Project({
+        skipAddingFilesFromTsConfig: true,
+        skipFileDependencyResolution: true,
+        compilerOptions: { allowJs: true, jsx: 4 },
+    });
+    const globs = [`${root}/**/*.{ts,tsx,js,jsx}`, `!${root}/**/*.d.ts`, ...IGNORE.map((d) => `!${root}/**/${d}/**`), ...exclude.map((g) => `!${root}/${g}`)];
+    project.addSourceFilesAtPaths(globs);
+    return { root, project, sourceFiles: project.getSourceFiles(), native: loadNativeConfig(root) };
+}
+function readJson(p) {
+    try {
+        return JSON.parse(fs.readFileSync(p, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function loadNativeConfig(root) {
+    const n = {
+        isExpo: false, dynamicConfig: false, hasIosConfig: false, hasAndroidConfig: false,
+        iosKeys: new Set(), iosEmpty: new Set(), androidPermissions: new Set(), expoPlugins: new Set(),
+    };
+    // Expo static config
+    const appJson = readJson(path.join(root, "app.json"));
+    const expo = appJson?.expo ?? appJson;
+    if (expo && typeof expo === "object" && (appJson?.expo || expo.name)) {
+        n.isExpo = true;
+        n.hasIosConfig = true;
+        n.hasAndroidConfig = true;
+        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}`);
+        }
+        for (const pl of expo.plugins ?? [])
+            n.expoPlugins.add(Array.isArray(pl) ? pl[0] : pl);
+    }
+    if (["app.config.ts", "app.config.js"].some((f) => fs.existsSync(path.join(root, f))) && !n.isExpo) {
+        n.isExpo = true;
+        n.dynamicConfig = true;
+    }
+    // Bare iOS: ios/<App>/Info.plist
+    const iosDir = path.join(root, "ios");
+    if (fs.existsSync(iosDir)) {
+        for (const d of fs.readdirSync(iosDir, { withFileTypes: true })) {
+            const plist = path.join(iosDir, d.name, "Info.plist");
+            if (d.isDirectory() && fs.existsSync(plist)) {
+                n.hasIosConfig = true;
+                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]);
+            }
+        }
+    }
+    // Bare Android manifest
+    const manifest = path.join(root, "android/app/src/main/AndroidManifest.xml");
+    if (fs.existsSync(manifest)) {
+        n.hasAndroidConfig = true;
+        for (const m of fs.readFileSync(manifest, "utf8").matchAll(/<uses-permission[^>]*android:name="([^"]+)"/g)) {
+            n.androidPermissions.add(m[1]);
+        }
+    }
+    return n;
+}

package/dist/reporters.d.ts

@@ -0,0 +1,4 @@
+import type { AnalyzeResult } from "./engine.js";
+export declare function terminal(r: AnalyzeResult): string;
+export declare const json: (r: AnalyzeResult) => string;
+export declare function sarif(r: AnalyzeResult): string;

package/dist/reporters.js

@@ -0,0 +1,35 @@
+import { rules } from "./rules/index.js";
+const c = (code) => (s) => (process.stdout.isTTY ? `\x1b[${code}m${s}\x1b[0m` : s);
+const red = c(31), yellow = c(33), cyan = c(36), dim = c(2), bold = c(1);
+export function terminal(r) {
+    const out = [];
+    let file = "";
+    for (const f of r.findings) {
+        if (f.file !== file) {
+            file = f.file;
+            out.push("", bold(file));
+        }
+        const sev = f.severity === "error" ? red("error") : f.severity === "warn" ? yellow("warn ") : cyan("info ");
+        out.push(`  ${f.line}:${f.column}  ${sev}  ${f.message}  ${dim(f.ruleId)}`);
+        out.push(dim(`           why: ${f.why}`), dim(`           fix: ${f.fix}`));
+    }
+    const errors = r.findings.filter((f) => f.severity === "error").length;
+    out.push("", `${r.findings.length} finding(s), ${errors} error(s). ` +
+        dim(`(${r.suppressed} suppressed, ${r.baselined} baselined, ${r.hidden} low-confidence hidden — use --strict to show)`));
+    return out.join("\n");
+}
+export const json = (r) => JSON.stringify(r, null, 2);
+export function sarif(r) {
+    return JSON.stringify({
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json", version: "2.1.0",
+        runs: [{
+                tool: { driver: { name: "ParityGuard", rules: rules.map((x) => ({ id: x.id, shortDescription: { text: x.title }, fullDescription: { text: x.explain } })) } },
+                results: r.findings.map((f) => ({
+                    ruleId: f.ruleId, level: f.severity === "error" ? "error" : f.severity === "warn" ? "warning" : "note",
+                    message: { text: `${f.message} ${f.why}` },
+                    locations: [{ physicalLocation: { artifactLocation: { uri: f.file }, region: { startLine: f.line, startColumn: f.column } } }],
+                    partialFingerprints: { parityGuard: f.fingerprint },
+                })),
+            }],
+    }, null, 2);
+}

package/dist/rules/helpers.d.ts

@@ -0,0 +1,19 @@
+import { Node } from "ts-morph";
+export type PlatformName = "ios" | "android";
+/** Recognises `Platform.OS === 'ios'` and variants. */
+export declare function asPlatformCheck(expr: Node): {
+    platform: PlatformName;
+    negated: boolean;
+} | undefined;
+export declare function endsWithExit(stmt: Node): boolean;
+export declare const pos: (n: Node) => {
+    file: string;
+    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

@@ -0,0 +1,35 @@
+import { Node, SyntaxKind } from "ts-morph";
+/** Recognises `Platform.OS === 'ios'` and variants. */
+export function asPlatformCheck(expr) {
+    if (!Node.isBinaryExpression(expr))
+        return undefined;
+    const op = expr.getOperatorToken().getKind();
+    const eq = op === SyntaxKind.EqualsEqualsEqualsToken || op === SyntaxKind.EqualsEqualsToken;
+    const neq = op === SyntaxKind.ExclamationEqualsEqualsToken || op === SyntaxKind.ExclamationEqualsToken;
+    if (!eq && !neq)
+        return undefined;
+    const [l, r] = [expr.getLeft(), expr.getRight()];
+    const [osSide, litSide] = l.getText() === "Platform.OS" ? [l, r] : r.getText() === "Platform.OS" ? [r, l] : [undefined, undefined];
+    if (!osSide || !litSide || !Node.isStringLiteral(litSide))
+        return undefined;
+    const v = litSide.getLiteralValue();
+    if (v !== "ios" && v !== "android")
+        return undefined;
+    return { platform: v, negated: neq };
+}
+export function endsWithExit(stmt) {
+    const last = Node.isBlock(stmt) ? stmt.getStatements().at(-1) : stmt;
+    return !!last && (Node.isReturnStatement(last) || Node.isThrowStatement(last) || Node.isContinueStatement(last) || Node.isBreakStatement(last));
+}
+export const pos = (n) => {
+    const sf = n.getSourceFile();
+    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.d.ts

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

package/dist/rules/index.js

@@ -0,0 +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"),
+    pg008, pg009, pg010,
+];

package/dist/rules/permissions.d.ts

@@ -0,0 +1,14 @@
+import type { Rule } from "../types.js";
+interface Capability {
+    id: string;
+    imports: string[];
+    iosKeys: string[];
+    androidPermissions: string[];
+    expoPlugins: string[];
+}
+export declare const capabilityData: {
+    dataVersion: string;
+    capabilities: Capability[];
+};
+export declare function makePermissionRule(platform: "ios" | "android"): Rule;
+export {};

package/dist/rules/permissions.js

@@ -0,0 +1,109 @@
+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()) {
+            const mod = imp.getModuleSpecifierValue();
+            for (const cap of capabilityData.capabilities) {
+                if (found.has(cap.id) || !cap.imports.some((i) => mod === i || mod.startsWith(i + "/")))
+                    continue;
+                const { line, column } = sf.getLineAndColumnAtPos(imp.getStart());
+                found.set(cap.id, { cap, file: sf.getFilePath(), line, column, mod });
+            }
+        }
+    }
+    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 or empty iOS usage description" : "Missing Android permission",
+        severity: "error",
+        confidence: "high",
+        explain: ios
+            ? "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
+            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 (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.d.ts

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

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

@@ -0,0 +1,58 @@
+import { Node, SyntaxKind } from "ts-morph";
+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). " +
+        "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;
+                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: `\`${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.`,
+                });
+            }
+            for (const bin of sf.getDescendantsOfKind(SyntaxKind.BinaryExpression)) {
+                if (bin.getOperatorToken().getKind() !== SyntaxKind.AmpersandAmpersandToken)
+                    continue;
+                const chk = asPlatformCheck(bin.getLeft());
+                if (!chk || Node.isIfStatement(bin.getParent()))
+                    continue;
+                report({
+                    ...pos(bin),
+                    confidence: "medium",
+                    message: `\`Platform.OS === '${chk.platform}' && …\` renders/runs on ${chk.platform} only.`,
+                    why: "The other platform gets no equivalent. Fine for iOS-only chrome, risky for functional UI.",
+                    fix: "Confirm the other platform doesn't need an equivalent, then add a parity-ignore comment with a reason.",
+                });
+            }
+        }
+    },
+};

package/dist/rules/pg002-incomplete-platform-select.d.ts

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

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

@@ -0,0 +1,39 @@
+import { Node, SyntaxKind } from "ts-morph";
+import { pos } from "./helpers.js";
+export const pg002 = {
+    id: "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. " +
+        "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)) {
+                if (call.getExpression().getText() !== "Platform.select")
+                    continue;
+                const arg = call.getArguments()[0];
+                if (!arg || !Node.isObjectLiteralExpression(arg))
+                    continue;
+                if (arg.getProperties().some((p) => Node.isSpreadAssignment(p)))
+                    continue; // can't know
+                const keys = new Set(arg.getProperties().map((p) => (Node.isPropertyAssignment(p) || Node.isShorthandPropertyAssignment(p) ? p.getName().replace(/['"]/g, "") : "")));
+                if (keys.has("default") || keys.has("native"))
+                    continue;
+                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/pg003-divergent-platform-files.d.ts

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

package/dist/rules/pg003-divergent-platform-files.js

@@ -0,0 +1,36 @@
+export const pg003 = {
+    id: "PG003",
+    title: "Platform-specific files export different names",
+    severity: "error",
+    confidence: "high",
+    explain: "`X.ios.tsx` and `X.android.tsx` are resolved by name from shared code, so their exports must match.",
+    check(ctx, report) {
+        const groups = new Map();
+        for (const sf of ctx.sourceFiles) {
+            const m = sf.getFilePath().match(/^(.*)\.(ios|android)\.(tsx?|jsx?)$/);
+            if (!m)
+                continue;
+            const key = `${m[1]}.${m[3]}`;
+            groups.set(key, { ...groups.get(key), [m[2]]: sf });
+        }
+        for (const { ios, android } of groups.values()) {
+            if (!ios || !android)
+                continue;
+            const a = new Set([...ios.getExportedDeclarations().keys()]);
+            const b = new Set([...android.getExportedDeclarations().keys()]);
+            const onlyIos = [...a].filter((x) => !b.has(x));
+            const onlyAndroid = [...b].filter((x) => !a.has(x));
+            if (!onlyIos.length && !onlyAndroid.length)
+                continue;
+            report({
+                file: ios.getFilePath(), line: 1, column: 1,
+                anchor: `${onlyIos.join(",")}|${onlyAndroid.join(",")}`,
+                message: `Export mismatch between .ios and .android files` +
+                    (onlyIos.length ? ` — only iOS exports: ${onlyIos.join(", ")}` : "") +
+                    (onlyAndroid.length ? ` — only Android exports: ${onlyAndroid.join(", ")}` : "") + ".",
+                why: "Shared code importing the missing name crashes or gets `undefined` on one platform.",
+                fix: "Export the same names from both files (or extract the shared surface into a common module).",
+            });
+        }
+    },
+};

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

@@ -0,0 +1,52 @@
+import type { Project, SourceFile } from "ts-morph";
+export type Severity = "error" | "warn" | "info";
+export type Confidence = "high" | "medium" | "low";
+export interface Finding {
+    ruleId: string;
+    severity: Severity;
+    confidence: Confidence;
+    message: string;
+    why: string;
+    fix: string;
+    file: string;
+    line: number;
+    column: number;
+    fingerprint: string;
+}
+export interface ReportInput {
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+    why: string;
+    fix: string;
+    confidence?: Confidence;
+    /** Stable text used for the baseline fingerprint (defaults to the source line). */
+    anchor?: string;
+}
+export interface NativeConfig {
+    isExpo: boolean;
+    /** app.config.ts/js exists and can't be statically evaluated. */
+    dynamicConfig: boolean;
+    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>;
+}
+export interface ProjectContext {
+    root: string;
+    project: Project;
+    sourceFiles: SourceFile[];
+    native: NativeConfig;
+}
+export interface Rule {
+    id: string;
+    title: string;
+    severity: Severity;
+    confidence: Confidence;
+    explain: string;
+    check(ctx: ProjectContext, report: (r: ReportInput) => void): void;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "parityguard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "bin": {
+    "parityguard": "dist/cli.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "data"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "check:fixtures": "node dist/cli.js check fixtures/bad-app",
+    "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"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2",
+    "vitest": "^5.1.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android",
+    "lint",
+    "cross-platform",
+    "typescript",
+    "expo"
+  ],
+  "overrides": {
+    "minimatch": "^11.0.7"
+  }
+}