expo-variant-check 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# expo-variant-check
+
+Catches the ways an Expo/EAS app-variant setup (development / preview /
+production, each installable side by side) silently drifts out of sync.
+Read-only — it never writes to your project, so it's safe to run in CI, a
+pre-commit hook, or just by hand before a build.
+
+## What it checks
+
+For every profile in `eas.json`, the resolved config is evaluated the same
+way EAS Build would evaluate it (by setting that profile's env vars and
+running `expo config --json`), then cross-checked for:
+
+- **`identity-collision`** — two or more profiles resolving to the same iOS
+  `bundleIdentifier` or Android `package`. Variants sharing an identity
+  overwrite each other on install instead of coexisting.
+- **`scheme-collision`** — more than one profile registering the
+  `expo-dev-client` generated deep link scheme. When two variants answer the
+  same scheme, the QR code from `expo start` can open the wrong installed
+  app.
+- **`channel-environment-mismatch`** — an EAS Update `channel` and
+  `environment` that are missing or named differently on the same profile.
+  This doesn't error at publish time — it silently ships the wrong
+  environment's values to a channel real users may already be on.
+- **`stale-native-project`** *(local only)* — a locally prebuilt
+  `android/`/`ios/` project whose identity doesn't match what the
+  currently-set `APP_VARIANT` resolves to, meaning `expo start` is pointing
+  at the wrong native project.
+
+## Usage
+
+```
+npx expo-variant-check
+```
+
+Run it from your Expo project root, wherever `eas.json` lives. It exits `1`
+if any check reports an error, `0` otherwise (warnings alone don't fail the
+run).
+
+### In CI
+
+Add this to an Expo project's own repo (not this one — this repo has no
+`eas.json` of its own, since it *is* the tool):
+
+```yaml
+# .github/workflows/variant-check.yml
+on: [pull_request]
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx expo-variant-check
+```
+
+## What it doesn't do
+
+It can't register your app's identifiers with external services — Firebase,
+Google Maps, push certificates, and similar still need manual per-variant
+setup. It also can't validate EAS-hosted environment variables (`eas env:list`)
+yet, since that needs an authenticated API call; today it only checks the
+inline `env` block and the `channel`/`environment` fields in `eas.json`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "expo-variant-check",
+  "version": "0.1.0",
+  "description": "Catches silent drift between Expo/EAS app variants before it ships: colliding deep link schemes, mismatched EAS Update channel/environment pairs, stale local native projects, and duplicate bundle identifiers. Read-only — safe for CI.",
+  "type": "module",
+  "bin": {
+    "expo-variant-check": "./src/cli.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@expo-variant-tools/core": "0.1.0"
+  },
+  "keywords": [
+    "expo",
+    "eas",
+    "eas-build",
+    "eas-update",
+    "app-variants",
+    "lint",
+    "doctor",
+    "ci"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/checks/channel-environment-mismatch.js

@@ -0,0 +1,40 @@
+/**
+ * Flags build profiles where `channel` and `environment` are inconsistent:
+ * set to different names, or only one of the two is present. A mismatch
+ * here doesn't error at build or publish time — it silently ships an
+ * update carrying the wrong environment's values to a channel real users
+ * may already be on.
+ *
+ * @param {{ name: string, channel: string|null, environment: string|null }[]} profiles
+ * @returns {Array<{level: string, check: string, message: string}>}
+ */
+export function checkChannelEnvironmentMismatch(profiles) {
+  const issues = [];
+
+  for (const profile of profiles) {
+    const { name, channel, environment } = profile;
+    if (!channel && !environment) continue; // nothing to cross-check
+
+    if (channel && !environment) {
+      issues.push({
+        level: "warning",
+        check: "channel-environment-mismatch",
+        message: `Profile "${name}" sets a channel ("${channel}") but no environment. EAS Update publishes to this channel will use whatever --environment flag is passed at the command line, which is easy to get wrong.`,
+      });
+    } else if (!channel && environment) {
+      issues.push({
+        level: "warning",
+        check: "channel-environment-mismatch",
+        message: `Profile "${name}" sets an environment ("${environment}") but no channel. Builds from this profile won't receive EAS Updates automatically.`,
+      });
+    } else if (channel !== environment) {
+      issues.push({
+        level: "warning",
+        check: "channel-environment-mismatch",
+        message: `Profile "${name}" has channel "${channel}" but environment "${environment}" — different names. If intentional, ignore this; if not, publishing with --environment ${environment} will land on the "${channel}" channel carrying the wrong values.`,
+      });
+    }
+  }
+
+  return issues;
+}

package/src/checks/identity-collision.js

@@ -0,0 +1,54 @@
+/**
+ * Flags build profiles that resolve to the same iOS bundle identifier or
+ * Android package name. Variants sharing an identity can't be installed
+ * side by side — installing one silently overwrites the other on device.
+ *
+ * @param {{ name: string, config: object }[]} resolvedProfiles
+ * @returns {Array<{level: string, check: string, message: string}>}
+ */
+export function checkIdentityCollisions(resolvedProfiles) {
+  const issues = [];
+  const byBundleId = new Map();
+  const byPackage = new Map();
+
+  for (const { name, config } of resolvedProfiles) {
+    const bundleId = config?.ios?.bundleIdentifier;
+    const pkg = config?.android?.package;
+
+    if (bundleId) {
+      const existing = byBundleId.get(bundleId) ?? [];
+      existing.push(name);
+      byBundleId.set(bundleId, existing);
+    }
+    if (pkg) {
+      const existing = byPackage.get(pkg) ?? [];
+      existing.push(name);
+      byPackage.set(pkg, existing);
+    }
+  }
+
+  for (const [bundleId, profiles] of byBundleId) {
+    if (profiles.length > 1) {
+      issues.push({
+        level: "error",
+        check: "identity-collision",
+        message: `iOS bundleIdentifier "${bundleId}" is shared by profiles: ${profiles.join(
+          ", "
+        )}. These builds will overwrite each other on install.`,
+      });
+    }
+  }
+  for (const [pkg, profiles] of byPackage) {
+    if (profiles.length > 1) {
+      issues.push({
+        level: "error",
+        check: "identity-collision",
+        message: `Android package "${pkg}" is shared by profiles: ${profiles.join(
+          ", "
+        )}. These builds will overwrite each other on install.`,
+      });
+    }
+  }
+
+  return issues;
+}

package/src/checks/scheme-collision.js

@@ -0,0 +1,43 @@
+/**
+ * Flags when more than one build profile's resolved config would register
+ * the generated `exp+<slug>` deep link scheme via the expo-dev-client
+ * plugin. The plugin adds this scheme by default whenever it's present,
+ * unless `addGeneratedScheme: false` is set. When two or more variants
+ * answer the same scheme, the QR code from `expo start` (and any deep link
+ * using it) may open the wrong installed app.
+ *
+ * @param {{ name: string, config: object }[]} resolvedProfiles
+ * @returns {Array<{level: string, check: string, message: string}>}
+ */
+export function checkSchemeCollisions(resolvedProfiles) {
+  const issues = [];
+  const claimants = [];
+
+  for (const { name, config } of resolvedProfiles) {
+    const plugins = config?.plugins ?? [];
+    const devClientEntry = plugins.find(
+      (p) => p === "expo-dev-client" || (Array.isArray(p) && p[0] === "expo-dev-client")
+    );
+    if (!devClientEntry) continue;
+
+    const options = Array.isArray(devClientEntry) ? devClientEntry[1] ?? {} : {};
+    // addGeneratedScheme defaults to true whenever the plugin is present
+    // and the option isn't explicitly set to false.
+    const claimsScheme = options.addGeneratedScheme !== false;
+    if (claimsScheme) {
+      claimants.push(name);
+    }
+  }
+
+  if (claimants.length > 1) {
+    issues.push({
+      level: "error",
+      check: "scheme-collision",
+      message: `More than one profile registers the generated deep link scheme: ${claimants.join(
+        ", "
+      )}. Only one variant should set addGeneratedScheme to true (typically development) — set it to false for the others.`,
+    });
+  }
+
+  return issues;
+}

package/src/checks/stale-native-project.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Flags when the locally prebuilt native project's identity doesn't match
+ * what the currently-set APP_VARIANT resolves to. This catches "I built
+ * preview locally, then forgot to prebuild --clean back to dev" — expo
+ * start silently keeps pointing at whichever native project is on disk.
+ *
+ * Skips gracefully if android/ or ios/ directories aren't present (the
+ * common case for Continuous Native Generation projects that gitignore
+ * them).
+ *
+ * @param {string} projectRoot
+ * @param {object} currentConfig - resolved config for the *currently set*
+ *   APP_VARIANT (e.g. from .env.local or the shell).
+ * @returns {Array<{level: string, check: string, message: string}>}
+ */
+export function checkStaleNativeProject(projectRoot, currentConfig) {
+  const issues = [];
+
+  const gradlePath = path.join(projectRoot, "android", "app", "build.gradle");
+  if (fs.existsSync(gradlePath)) {
+    const gradle = fs.readFileSync(gradlePath, "utf8");
+    const match = gradle.match(/applicationId\s+["']([^"']+)["']/);
+    const nativePackage = match?.[1];
+    const expectedPackage = currentConfig?.android?.package;
+    if (nativePackage && expectedPackage && nativePackage !== expectedPackage) {
+      issues.push({
+        level: "warning",
+        check: "stale-native-project",
+        message: `android/app/build.gradle has applicationId "${nativePackage}", but the currently resolved config expects "${expectedPackage}". Run APP_VARIANT=<variant> npx expo prebuild --clean to regenerate it.`,
+      });
+    }
+  }
+
+  const iosDir = path.join(projectRoot, "ios");
+  if (fs.existsSync(iosDir)) {
+    const pbxprojPath = findPbxproj(iosDir);
+    if (pbxprojPath) {
+      const pbxproj = fs.readFileSync(pbxprojPath, "utf8");
+      const match = pbxproj.match(/PRODUCT_BUNDLE_IDENTIFIER\s*=\s*([^\s;]+);/);
+      const nativeBundleId = match?.[1];
+      const expectedBundleId = currentConfig?.ios?.bundleIdentifier;
+      if (nativeBundleId && expectedBundleId && nativeBundleId !== expectedBundleId) {
+        issues.push({
+          level: "warning",
+          check: "stale-native-project",
+          message: `ios project has PRODUCT_BUNDLE_IDENTIFIER "${nativeBundleId}", but the currently resolved config expects "${expectedBundleId}". Run APP_VARIANT=<variant> npx expo prebuild --clean to regenerate it.`,
+        });
+      }
+    }
+  }
+
+  return issues;
+}
+
+function findPbxproj(iosDir) {
+  const entries = fs.readdirSync(iosDir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name.endsWith(".xcodeproj")) {
+      const candidate = path.join(iosDir, entry.name, "project.pbxproj");
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+  return null;
+}

package/src/cli.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+import { readEasJson, getBuildProfiles, resolveExpoConfig } from "@expo-variant-tools/core";
+import { checkIdentityCollisions } from "./checks/identity-collision.js";
+import { checkSchemeCollisions } from "./checks/scheme-collision.js";
+import { checkChannelEnvironmentMismatch } from "./checks/channel-environment-mismatch.js";
+import { checkStaleNativeProject } from "./checks/stale-native-project.js";
+import { printReport } from "./report.js";
+
+function main() {
+  const projectRoot = process.cwd();
+
+  let easJson;
+  try {
+    easJson = readEasJson(projectRoot);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
+
+  const profiles = getBuildProfiles(easJson);
+  if (profiles.length === 0) {
+    console.error("No build profiles found in eas.json.");
+    process.exit(1);
+  }
+
+  // Resolve the config as EAS Build would evaluate it for each profile,
+  // by setting that profile's env vars and shelling out to `expo config`.
+  const resolvedProfiles = [];
+  for (const profile of profiles) {
+    const envVars = profile.appVariant ? { APP_VARIANT: profile.appVariant } : {};
+    try {
+      const config = resolveExpoConfig(projectRoot, envVars);
+      resolvedProfiles.push({ name: profile.name, config });
+    } catch (err) {
+      console.warn(
+        `Could not resolve config for profile "${profile.name}" (skipping): ${err.message}`
+      );
+    }
+  }
+
+  const issues = [
+    ...checkIdentityCollisions(resolvedProfiles),
+    ...checkSchemeCollisions(resolvedProfiles),
+    ...checkChannelEnvironmentMismatch(profiles),
+  ];
+
+  // The stale-native-project check needs the config for whatever
+  // APP_VARIANT is *currently* set locally, not a specific EAS profile.
+  const currentAppVariant = process.env.APP_VARIANT;
+  const currentProfile = profiles.find((p) => p.appVariant === currentAppVariant);
+  const currentResolved = currentProfile
+    ? resolvedProfiles.find((p) => p.name === currentProfile.name)
+    : resolvedProfiles[0];
+  if (currentResolved) {
+    issues.push(...checkStaleNativeProject(projectRoot, currentResolved.config));
+  }
+
+  printReport(issues);
+  process.exit(issues.some((i) => i.level === "error") ? 1 : 0);
+}
+
+main();

package/src/index.js

@@ -0,0 +1,6 @@
+// Programmatic entry point, for anyone who wants to run checks from a
+// script instead of the CLI (e.g. a custom CI step or another tool).
+export { checkIdentityCollisions } from "./checks/identity-collision.js";
+export { checkSchemeCollisions } from "./checks/scheme-collision.js";
+export { checkChannelEnvironmentMismatch } from "./checks/channel-environment-mismatch.js";
+export { checkStaleNativeProject } from "./checks/stale-native-project.js";

package/src/report.js

@@ -0,0 +1,21 @@
+const SYMBOLS = { error: "\u2717", warning: "\u26A0" };
+
+/**
+ * Prints a plain-text report of issues to stdout.
+ * @param {Array<{level: string, check: string, message: string}>} issues
+ */
+export function printReport(issues) {
+  if (issues.length === 0) {
+    console.log("\u2713 No variant issues found.");
+    return;
+  }
+
+  for (const issue of issues) {
+    console.log(`${SYMBOLS[issue.level] ?? "-"} [${issue.check}] ${issue.message}`);
+  }
+
+  const errors = issues.filter((i) => i.level === "error").length;
+  const warnings = issues.filter((i) => i.level === "warning").length;
+  console.log("");
+  console.log(`${errors} error(s), ${warnings} warning(s).`);
+}