parityguard 0.0.0-stage → 0.1.0-alpha.0

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,150 @@
-# 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. 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 |
+| 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.
+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 `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.
+
+## 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.
+- 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`.
+
+## 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.

package/data/capabilities.json

@@ -0,0 +1,22 @@
+{
+  "dataVersion": "2026.11.0",
+  "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"] }
+  ]
+}

package/dist/cli.d.ts

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

package/dist/cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+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>
+
+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" },
+            help: { type: "boolean", short: "h", default: false },
+        },
+    });
+    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/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,66 @@
+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 report = (r) => {
+            const text = fs.readFileSync(r.file, "utf8").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)) {
+                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;
+            }
+            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,67 @@
+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(), 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;
+        Object.keys(expo.ios?.infoPlist ?? {}).forEach((k) => n.iosKeys.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;
+                for (const m of fs.readFileSync(plist, "utf8").matchAll(/<key>([^<]+)<\/key>/g))
+                    n.iosKeys.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,13 @@
+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;
+};

package/dist/rules/helpers.js

@@ -0,0 +1,28 @@
+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 };
+};

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,5 @@
+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 { makePermissionRule } from "./permissions.js";
+export const rules = [pg001, pg002, pg003, makePermissionRule("ios"), makePermissionRule("android")];

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,56 @@
+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) {
+    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()];
+}
+export function makePermissionRule(platform) {
+    const ios = platform === "ios";
+    return {
+        id: ios ? "PG006" : "PG007",
+        title: ios ? "Missing 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.",
+        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 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.`,
+                });
+            }
+        },
+    };
+}

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,40 @@
+import { Node, SyntaxKind } from "ts-morph";
+import { asPlatformCheck, endsWithExit, pos } from "./helpers.js";
+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).",
+    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";
+                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.`,
+                    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,34 @@
+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.",
+    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;
+                report({
+                    ...pos(call),
+                    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/types.d.ts

@@ -0,0 +1,50 @@
+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>;
+    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,46 @@
 {
   "name": "parityguard",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.0",
+  "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"
+  },
+  "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/",
+    "tag": "alpha"
+  },
+  "keywords": [
+    "react-native",
+    "ios",
+    "android",
+    "lint",
+    "cross-platform",
+    "typescript",
+    "expo"
+  ]
+}