nativekeel 0.1.0

package/src/plan.js

@@ -0,0 +1,357 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { UPGRADE_HELPER_URL, NEW_ARCH_ONLY_MINOR } from './rules.js';
+import { SITE_URL } from './config.js';
+import { COMPAT, bestRange } from './compat.js';
+
+// Turns a scan result into an ordered upgrade plan. The order matters more than the steps:
+// stop leaks first, then remove blockers, switch architecture on the current version,
+// and only then move React Native itself.
+
+function packageManager(root) {
+  let dir = root;
+  while (true) {
+    if (fs.existsSync(path.join(dir, 'pnpm-lock.yaml'))) return 'pnpm';
+    if (fs.existsSync(path.join(dir, 'yarn.lock'))) return 'yarn';
+    if (fs.existsSync(path.join(dir, 'bun.lockb')) || fs.existsSync(path.join(dir, 'bun.lock'))) return 'bun';
+    if (fs.existsSync(path.join(dir, 'package-lock.json'))) return 'npm';
+    const parent = path.dirname(dir);
+    if (parent === dir) return 'npm';
+    dir = parent;
+  }
+}
+
+const commands = {
+  npm: { add: 'npm install', remove: 'npm uninstall' },
+  yarn: { add: 'yarn add', remove: 'yarn remove' },
+  pnpm: { add: 'pnpm add', remove: 'pnpm remove' },
+  bun: { add: 'bun add', remove: 'bun remove' },
+};
+
+// Intermediate stops roughly every three minors keep each diff reviewable.
+export function upgradeHops(from, to) {
+  const start = Number(from.split('.')[1]);
+  const end = Number(to.split('.')[1]);
+  const hops = [];
+  for (let m = start + 3; m < end; m += 3) hops.push(`0.${m}.0`);
+  hops.push(to);
+  return hops;
+}
+
+const WEIGHTS = {
+  'upgrade-rn': (f) => Number(f.to.split('.')[1]) - Number(f.from.split('.')[1]),
+  'upgrade-expo': (f) => (f.to - f.from) * 2,
+  'enable-new-arch': () => 6,
+  'replace-dep': (f) => (f.noNewArch ? 4 : f.native ? 3 : 1),
+  'bump-dep': (f) => (f.native ? 1 : 0.5),
+  secret: (f) => (f.bundled ? 2 : 1),
+  'target-sdk': () => 2,
+  'align-16kb': (f) => f.libs.length,
+  'privacy-manifest': () => 1,
+  'remove-flipper': () => 1,
+  'enable-hermes': () => 2,
+  manifest: () => 0.5,
+  ats: () => 0.5,
+  'min-sdk': () => 1,
+  'ios-min': () => 1,
+  'remove-dep': () => 0.25,
+  'known-issue': () => 1,
+  compat: () => 1,
+  'app-dependency-provider': () => 1,
+  'interop-job': () => 2,
+  'podfile-cli-require': () => 0.25,
+  rctappdelegate: () => 2,
+  'patch-artifacts': () => 0.5,
+  'patch-version': () => 1,
+  'folly-flags': () => 0.25,
+  'default-react-host': () => 0.25,
+};
+
+export function complexity(findings) {
+  const score = Math.round(
+    findings.reduce((sum, f) => sum + (f.fix && WEIGHTS[f.fix.kind] ? WEIGHTS[f.fix.kind](f.fix) : 0), 0),
+  );
+  const size = score < 8 ? 'Small' : score < 20 ? 'Medium' : score < 40 ? 'Large' : 'Extra large';
+  return { score, size };
+}
+
+export function buildPlan(result) {
+  const pm = commands[packageManager(result.project.root)];
+  const installed = new Set(result.deps.map((d) => d.name));
+  const byKind = (kind) => result.findings.filter((f) => f.fix && f.fix.kind === kind).map((f) => f.fix);
+  const phases = [];
+
+  const secrets = byKind('secret');
+  if (secrets.length) {
+    const steps = [];
+    for (const s of secrets.filter((x) => x.bundled)) {
+      if (/^\.env/.test(s.file)) {
+        steps.push(`**Rotate the secret values in \`${s.file}\`.** They are compiled into the JavaScript bundle, so every installed copy of the app contains them.`);
+      } else {
+        steps.push(`**Revoke the ${s.label}** in \`${s.file}:${s.line}\` at the provider today. Removing it from code is not enough: every installed copy of the app still contains it.`);
+      }
+    }
+    if (secrets.some((x) => x.bundled)) {
+      steps.push('Move every call that needs a secret behind your own backend (a Cloud Function, API route or edge function). The app should only hold keys that are designed to be public.');
+    }
+    for (const s of secrets.filter((x) => !x.bundled)) {
+      if (s.label === 'Signing passwords') {
+        steps.push(`**Move the signing passwords out of \`${s.file}\`** into \`~/.gradle/gradle.properties\` or CI environment variables; change them if the keystore ever left your control.`);
+      } else {
+        steps.push(`**Rotate the ${s.label}** in \`${s.file}\`, then load it from environment variables or a secret manager and add the file to \`.gitignore\`.`);
+      }
+    }
+    steps.push('The old values stay in git history. Rotation is what makes them useless; rewriting history (e.g. `git filter-repo`) is optional cleanup.');
+    phases.push({ title: 'Stop the leaks', why: 'Leaked keys cost money and data from the moment someone finds them. Nothing else in this plan is as urgent.', steps });
+  }
+
+  const sdk = byKind('target-sdk')[0];
+  if (sdk) {
+    phases.push({
+      title: 'Meet the Google Play target SDK',
+      why: 'Below the required level Google Play rejects updates or hides the app from new users.',
+      steps: [
+        `Set \`targetSdkVersion = ${sdk.to}\` and \`compileSdkVersion = ${sdk.to}\` in \`android/build.gradle\`.`,
+        `Read the Android behavior changes for every API level between ${sdk.from} and ${sdk.to}; edge-to-edge display and foreground service types are the usual surprises.`,
+        'Build a release bundle and test on a device running the newest Android version.',
+      ],
+    });
+  }
+
+  const known = byKind('known-issue');
+  if (known.length) {
+    phases.push({
+      title: 'Avoid known traps',
+      why: 'These exact version combinations broke real apps. Handle them before the step that would trigger them.',
+      steps: known.map((k) => `**${k.title}.** ${k.detail}`),
+    });
+  }
+
+  const unusedDeps = byKind('remove-dep');
+  if (unusedDeps.length) {
+    phases.push({
+      title: 'Remove unused packages',
+      why: 'Every package you delete is one you never have to upgrade. Native modules also cut build time.',
+      steps: [
+        `\`${pm.remove} ${unusedDeps.map((d) => d.name).join(' ')}\`${unusedDeps.some((d) => d.native) ? ', then reinstall pods' : ''}.`,
+        'Search the code once more for each name before removing it (dynamic requires are invisible to static analysis), then build both platforms.',
+      ],
+    });
+  }
+
+  const storeSteps = [];
+  if (byKind('privacy-manifest').length) {
+    storeSteps.push('Add `PrivacyInfo.xcprivacy` to the iOS app target. Start from the file in the React Native template and declare the required-reason APIs your app and SDKs use (UserDefaults, file timestamps, system boot time, disk space).');
+  }
+  const align = byKind('align-16kb')[0];
+  if (align) {
+    storeSteps.push(`Fix 16 KB alignment for ${align.libs.map((l) => `\`${l}\``).join(', ')}: find which package ships each library (\`grep -rl <lib> node_modules/*/android\`) and update it; libraries you build yourself need NDK r28+.`);
+  }
+  if (storeSteps.length) {
+    phases.push({
+      title: 'Meet App Store and Google Play requirements',
+      why: 'These block your next store submission regardless of anything else in this plan.',
+      steps: storeSteps,
+    });
+  }
+
+  const securitySteps = [];
+  for (const m of byKind('manifest')) {
+    securitySteps.push(m.attr === 'android:debuggable'
+      ? 'Remove `android:debuggable="true"` from `android/app/src/main/AndroidManifest.xml`.'
+      : 'Move `android:usesCleartextTraffic="true"` to `android/app/src/debug/AndroidManifest.xml`, or allow only specific hosts with a network security config.');
+  }
+  for (const a of byKind('ats')) {
+    securitySteps.push(`In \`${a.file}\`, set \`NSAllowsArbitraryLoads\` to false and list only the hosts that need HTTP under \`NSExceptionDomains\`.`);
+  }
+  if (securitySteps.length) {
+    phases.push({ title: 'Tighten transport security', why: 'Unencrypted traffic exposes user data on public networks.', steps: securitySteps });
+  }
+
+  const cleanup = [];
+  for (const f of byKind('default-react-host')) {
+    cleanup.push(`When moving to React Native 0.80+, change \`DefaultReactHost.getDefaultReactHost(context, host)\` in \`${f.file}\` to pass \`null\` as a third argument.`);
+  }
+  for (const f of byKind('folly-flags')) {
+    cleanup.push(`In \`${f.file}\`, add \`-DFOLLY_CFG_NO_COROUTINES=1\` and \`-DFOLLY_HAVE_CLOCK_GETTIME=1\` to OTHER_CPLUSPLUSFLAGS (Debug and Release) before moving to React Native 0.80.`);
+  }
+  for (const p of byKind('patch-artifacts')) {
+    cleanup.push(`Recreate \`patches/${p.file}\` without build output: reinstall \`${p.pkg}\`, re-apply the source edits, then \`npx patch-package ${p.pkg} --exclude '(^package\\.json$|/build/)'\`.`);
+  }
+  for (const p of byKind('patch-version')) {
+    cleanup.push(`\`patches/${p.file}\` targets ${p.pkg} ${p.version} but ${p.installed} is installed: check whether the fix is still needed, then recreate or delete it.`);
+  }
+  if (byKind('podfile-cli-require').length) {
+    cleanup.push("Delete `require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'` from `ios/Podfile`; `use_native_modules!` comes from React Native.");
+  }
+  if (byKind('remove-flipper').length) {
+    cleanup.push('Remove Flipper: delete the `com.facebook.flipper` dependencies and `FLIPPER_VERSION` on Android, `use_flipper!` / Flipper config in the Podfile, and the `ReactNativeFlipper` initialization code. Use React Native DevTools instead.');
+  }
+  if (byKind('enable-hermes').length) {
+    cleanup.push('Switch to Hermes: set `hermesEnabled=true` in `android/gradle.properties` and `:hermes_enabled => true` in the Podfile, then test anything that relied on JavaScriptCore behavior (Intl, Date parsing).');
+  }
+  if (cleanup.length) {
+    phases.push({ title: 'Remove legacy tooling', why: 'Leftovers from older templates break on newer React Native versions; removing them first shrinks the upgrade diff.', steps: cleanup });
+  }
+
+  const replace = byKind('replace-dep').sort((a, b) => Number(b.noNewArch) - Number(a.noNewArch) || Number(b.native) - Number(a.native));
+  if (replace.length) {
+    phases.push({
+      title: 'Replace blocking and abandoned packages',
+      why: 'These packages decide how far you can upgrade. Swap them while the app still runs on its current version, so every problem has one cause.',
+      steps: replace.map((d) => {
+        const reason = [d.noNewArch && 'no New Architecture support', d.unmaintained && 'unmaintained'].filter(Boolean).join(', ');
+        const owned = d.alternatives.find((a) => installed.has(a));
+        if (owned) {
+          return `\`${d.name}\` (${reason}${d.native ? ', native' : ''}). You already use \`${owned}\`: move the remaining usage there, then \`${pm.remove} ${d.name}\`.`;
+        }
+        const to = d.alternatives[0];
+        const cmd = to ? ` \`${pm.remove} ${d.name} && ${pm.add} ${to}\`` : '';
+        const options = d.alternatives.length ? `Options: ${d.alternatives.map((a) => `\`${a}\``).join(', ')}.${cmd}` : 'No known replacement: check for a maintained fork, or vendor and patch it with `patch-package`.';
+        return `\`${d.name}\` (${reason}${d.native ? ', native' : ''}). ${options}`;
+      }),
+    });
+  }
+
+  const nativeBumps = byKind('bump-dep').filter((d) => d.native);
+  if (nativeBumps.length) {
+    phases.push({
+      title: 'Update native modules on the current React Native version',
+      why: 'Newer releases of native modules usually add New Architecture support. Pick the newest release that still supports your current React Native version; check each changelog for its minimum.',
+      steps: nativeBumps.map((d) => `\`${d.name}\` ${d.from} → ${d.to}`),
+    });
+  }
+
+  const depProvider = byKind('app-dependency-provider')[0];
+  const arch = byKind('enable-new-arch')[0];
+  if (depProvider && !arch) {
+    phases.push({
+      title: 'Fix the iOS AppDelegate',
+      why: 'With the New Architecture on, this is a launch crash in Release builds.',
+      steps: [`In \`${depProvider.file}\`: \`#import <ReactAppDependencyProvider/RCTAppDependencyProvider.h>\` and \`self.dependencyProvider = [RCTAppDependencyProvider new];\` before \`[super application:didFinishLaunchingWithOptions:]\`.`],
+    });
+  }
+  if (arch) {
+    const steps = [];
+    for (const j of byKind('interop-job')) {
+      steps.push(`Patch \`${j.name}\` with patch-package so its ${j.methods.length} Kotlin @ReactMethods return Unit instead of a coroutine Job (wrap \`scope.launch { }\` in a helper that returns Unit and rename \`return@launch\` labels). Otherwise the module fails to load on Android.`);
+    }
+    if (depProvider) {
+      steps.push(`In \`${depProvider.file}\`, add \`#import <ReactAppDependencyProvider/RCTAppDependencyProvider.h>\` and \`self.dependencyProvider = [RCTAppDependencyProvider new];\` before calling super. Without it the switch causes a launch crash in Release.`);
+    }
+    if (result.project.managed) {
+      steps.push('Set `"newArchEnabled": true` in `app.json` (under `expo`), then run `npx expo prebuild --clean` and build.');
+    } else {
+      if (arch.platforms.includes('android')) steps.push('Android: set `newArchEnabled=true` in `android/gradle.properties`.');
+      if (arch.platforms.includes('ios')) steps.push('iOS: set `"newArchEnabled": "true"` in `ios/Podfile.properties.json` (or run `RCT_NEW_ARCH_ENABLED=1 bundle exec pod install`).');
+    }
+    for (const c of byKind('compat').filter((x) => x.forNewArch && x.range)) {
+      steps.unshift(`First move \`${c.name}\` to ${c.range}: the installed version does not support the New Architecture on this React Native version.`);
+    }
+    steps.push('Clean everything (`./gradlew clean`, `watchman watch-del-all`, delete `ios/build` and `ios/Pods`). Switching architecture without a clean build fails on stale codegen output (e.g. missing `Native…Spec` classes).');
+    steps.push('Build debug and release on both platforms.');
+    steps.push('Click through every screen that uses a native module. Interop-layer problems show up at runtime, not at build time.');
+    phases.push({
+      title: 'Turn on the New Architecture on your current version',
+      why: `React Native 0.${NEW_ARCH_ONLY_MINOR} removed the legacy architecture. Switching now, before changing the React Native version, keeps the two kinds of breakage apart.`,
+      steps,
+    });
+  }
+
+  const rn = byKind('upgrade-rn')[0];
+  if (rn) {
+    let from = rn.from;
+    const tracked = result.deps.filter((d) => COMPAT[d.name]);
+    const lastRange = {};
+    const steps = upgradeHops(rn.from, rn.to).map((to) => {
+      const minor = Number(to.split('.')[1]);
+      const bumps = tracked
+        .map((d) => {
+          const best = bestRange(d.name, minor, true);
+          // Prefer staying on the installed major when it still supports this hop.
+          const major = d.version ? Number(d.version.split('.')[0]) : null;
+          const same = major !== null && best && Number(best.from.split('.')[0]) !== major ? bestRange(d.name, minor, true, { major }) : null;
+          return { name: d.name, best, same };
+        })
+        .filter((b) => b.best && (b.same || b.best).range !== lastRange[b.name])
+        .map((b) => {
+          lastRange[b.name] = (b.same || b.best).range;
+          return b.same ? `\`${b.name}\` ${b.same.range} (or ${b.best.range}, a major migration)` : `\`${b.name}\` ${b.best.range}`;
+        });
+      const step = `${from} → ${to}: apply the diff from ${UPGRADE_HELPER_URL(from, to)}${bumps.length ? `, move ${bumps.join(' and ')}` : ''}, reinstall pods, build both platforms, commit.`;
+      from = to;
+      return step;
+    });
+    steps.push('Bump `react`, `@react-native/*` packages and the Metro/Babel config to the versions the Upgrade Helper shows for the target.');
+    const patchesReview = byKind('patches-review')[0];
+    if (patchesReview) {
+      steps.push(`After every hop, re-check ${patchesReview.patches.map((x) => `\`patches/${x.file}\``).join(', ')}: still applies (\`npx patch-package\`), still needed, not undoing what the new version expects.`);
+    }
+    steps.push('If `pod install` reports that a React Native dependency (fast_float, hermes-engine, …) differs from Podfile.lock, delete `ios/Pods` and `ios/Podfile.lock` and install again; library pods keep the versions their podspecs pin.');
+    steps.push('Update the Gradle version by editing `android/gradle/wrapper/gradle-wrapper.properties`: `./gradlew wrapper` fails because the new React Native Gradle plugin already needs the new Gradle.');
+    phases.push({
+      title: `Upgrade React Native ${rn.from} → ${rn.to}`,
+      why: 'Hopping a few minors at a time gives small diffs you can actually review and bisect when something breaks.',
+      steps,
+    });
+  }
+
+  const expo = byKind('upgrade-expo')[0];
+  if (expo) {
+    const steps = [];
+    for (let v = expo.from + 1; v <= expo.to; v++) steps.push(`SDK ${v - 1} → ${v}: \`npx expo install expo@^${v}.0.0 --fix\`, read the SDK ${v} changelog, run \`npx expo-doctor\`, build.`);
+    phases.push({ title: `Upgrade Expo SDK ${expo.from} → ${expo.to}`, why: 'Expo only supports one SDK step at a time reliably.', steps });
+  }
+
+  const jsBumps = byKind('bump-dep').filter((d) => !d.native);
+  if (jsBumps.length) {
+    phases.push({
+      title: 'Update JavaScript-only packages',
+      why: 'These do not block the upgrade. Do them last, one major at a time, following each migration guide.',
+      steps: jsBumps.map((d) => `\`${d.name}\` ${d.from} → ${d.to}`),
+    });
+  }
+
+  const minimums = [...byKind('min-sdk').map((m) => `Android minSdk → ${m.to}`), ...byKind('ios-min').map((m) => `iOS deployment target → ${m.to}`)];
+  if (minimums.length) {
+    // Raise minimums right before the React Native upgrade that requires them.
+    const at = phases.findIndex((p) => p.title.startsWith('Upgrade React Native'));
+    phases.splice(at >= 0 ? at : phases.length, 0, {
+      title: 'Raise platform minimums',
+      why: 'Current React Native no longer supports older OS versions. Check your analytics for how many users this drops before you ship.',
+      steps: minimums,
+    });
+  }
+
+  phases.push({
+    title: 'Verify before you ship',
+    why: 'An upgrade is done when the release build works on real devices, not when it compiles.',
+    steps: [
+      'Release builds on both platforms (`./gradlew bundleRelease`, Xcode Archive).',
+      'Test on a low-end Android device and on the newest iOS and Android versions.',
+      'Ship to internal testing / TestFlight first and watch crash-free sessions for a few days before a staged rollout.',
+      'Run `npx nativekeel` again: the report should have no critical or high findings.',
+    ],
+  });
+
+  return { phases, complexity: complexity(result.findings) };
+}
+
+export function planToMarkdown(result, plan) {
+  const p = result.project;
+  const lines = [
+    `# Upgrade plan: ${p.name || 'your app'}`,
+    '',
+    `Generated by NativeKeel on ${result.scannedAt.slice(0, 10)}.  `,
+    `React Native ${p.reactNative || '-'}${p.expo ? ` · Expo ${p.expo}` : ''} → latest ${result.latest.reactNative || '-'}.  `,
+    `Estimated scope: **${plan.complexity.size}** (score ${plan.complexity.score}).`,
+    '',
+  ];
+  plan.phases.forEach((phase, i) => {
+    lines.push(`## ${i + 1}. ${phase.title}`, '', `_${phase.why}_`, '');
+    phase.steps.forEach((s) => lines.push(`- [ ] ${s}`));
+    lines.push('');
+  });
+  lines.push('---', `No time to do it yourself? We do fixed-price upgrades on a branch of your repo: ${SITE_URL}/#services`);
+  return `${lines.join('\n')}\n`;
+}

package/src/project.js

@@ -0,0 +1,112 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const readText = (file) => {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+};
+
+const readJson = (file) => {
+  const text = readText(file);
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+};
+
+export function cleanVersion(v) {
+  const m = String(v).match(/(\d+)\.(\d+)(?:\.(\d+))?/);
+  return m ? `${m[1]}.${m[2]}.${m[3] || 0}` : null;
+}
+
+// Monorepos hoist packages, so look in every node_modules from the app up to the filesystem root.
+export function findPackageDir(root, name) {
+  let dir = root;
+  while (true) {
+    const candidate = path.join(dir, 'node_modules', name);
+    if (fs.existsSync(path.join(candidate, 'package.json'))) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+export function installedVersion(root, name) {
+  const dir = findPackageDir(root, name);
+  const pkg = dir && readJson(path.join(dir, 'package.json'));
+  return pkg ? pkg.version : null;
+}
+
+export function loadProject(root) {
+  const pkg = readJson(path.join(root, 'package.json'));
+  if (!pkg) throw new Error(`No package.json found in ${root}`);
+  const deps = { ...(pkg.dependencies || {}) };
+  // Monorepos often keep react-native in devDependencies; autolinking still links native modules from there.
+  const devDeps = { ...(pkg.devDependencies || {}) };
+  const declared = (name) => deps[name] || devDeps[name];
+  if (!declared('react-native') && !declared('expo')) {
+    throw new Error('This does not look like a React Native app (no react-native or expo dependency). Run it inside your app folder.');
+  }
+
+  const hasAndroid = fs.existsSync(path.join(root, 'android'));
+  const hasIos = fs.existsSync(path.join(root, 'ios'));
+  const appConfig = readJson(path.join(root, 'app.json'));
+
+  return {
+    root,
+    name: pkg.name,
+    deps,
+    devDeps,
+    rnVersion: cleanVersion(installedVersion(root, 'react-native') || declared('react-native') || ''),
+    expoVersion: declared('expo') ? cleanVersion(installedVersion(root, 'expo') || declared('expo')) : null,
+    // Expo "managed" apps generate android/ and ios/ at build time (Continuous Native Generation).
+    managed: !!declared('expo') && !hasAndroid && !hasIos,
+    hasNodeModules: !!findPackageDir(root, 'react-native'),
+    newArch: detectNewArch(root, appConfig),
+    android: hasAndroid ? detectAndroid(root) : null,
+  };
+}
+
+// Returns { android, ios } with true / false / null (not set, so the React Native default applies)
+function detectNewArch(root, appConfig) {
+  const result = { android: null, ios: null };
+
+  const gradle = readText(path.join(root, 'android', 'gradle.properties'));
+  const g = gradle && gradle.match(/^\s*newArchEnabled\s*=\s*(true|false)/m);
+  if (g) result.android = g[1] === 'true';
+
+  const podProps = readJson(path.join(root, 'ios', 'Podfile.properties.json'));
+  if (podProps && podProps.newArchEnabled !== undefined) result.ios = String(podProps.newArchEnabled) === 'true';
+
+  const podfile = readText(path.join(root, 'ios', 'Podfile'));
+  const p = podfile && podfile.match(/RCT_NEW_ARCH_ENABLED'?\]?\s*=\s*'?([01]|true|false)/);
+  if (p && result.ios === null) result.ios = p[1] === '1' || p[1] === 'true';
+
+  const expo = appConfig && appConfig.expo;
+  if (expo) {
+    const flag = (platform) =>
+      expo[platform] && expo[platform].newArchEnabled !== undefined ? expo[platform].newArchEnabled : expo.newArchEnabled;
+    for (const platform of ['android', 'ios']) {
+      if (result[platform] === null && flag(platform) !== undefined) result[platform] = !!flag(platform);
+    }
+  }
+  return result;
+}
+
+// Reads targetSdk / compileSdk from the usual places: root ext block or app/build.gradle(.kts).
+function detectAndroid(root) {
+  const files = ['build.gradle', 'build.gradle.kts', 'app/build.gradle', 'app/build.gradle.kts']
+    .map((f) => readText(path.join(root, 'android', f)))
+    .filter(Boolean)
+    .join('\n');
+  const num = (key) => {
+    const m = files.match(new RegExp(`\\b${key}(?:Version)?\\s*=?\\s*(\\d{2})\\b`));
+    return m ? Number(m[1]) : null;
+  };
+  return { targetSdk: num('targetSdk'), compileSdk: num('compileSdk'), minSdk: num('minSdk') };
+}

package/src/registry.js

@@ -0,0 +1,89 @@
+const UA = { 'User-Agent': 'nativekeel' };
+
+export async function fetchJson(url, headers = {}) {
+  try {
+    const res = await fetch(url, { headers: { ...UA, ...headers }, signal: AbortSignal.timeout(30000) });
+    if (!res.ok) return null;
+    return await res.json();
+  } catch {
+    return null;
+  }
+}
+
+// All network access goes through one `get` function so tests can replace it.
+export function createRegistry(get = fetchJson) {
+  return {
+    // React Native Directory supports looking up many packages in one request.
+    async directoryInfo(names) {
+      const out = {};
+      for (let i = 0; i < names.length; i += 25) {
+        const chunk = names.slice(i, i + 25).map(encodeURIComponent).join(',');
+        const data = await get(`https://reactnative.directory/api/library?name=${chunk}`);
+        if (data) Object.assign(out, data);
+      }
+      return out;
+    },
+
+    async npmLatest(names, concurrency = 12) {
+      const out = {};
+      const queue = [...names];
+      const worker = async () => {
+        while (queue.length) {
+          const name = queue.shift();
+          const data = await get(`https://registry.npmjs.org/${name.replace('/', '%2F')}/latest`);
+          out[name] = data ? data.version : null;
+        }
+      };
+      await Promise.all(Array.from({ length: concurrency }, worker));
+      return out;
+    },
+
+    // Publish date of each package's latest version. Needs the full packument (the abbreviated
+    // one only has a `modified` stamp that also moves on metadata edits), so call it only for
+    // the few packages where release recency decides the verdict.
+    async publishDates(names, concurrency = 8) {
+      const out = {};
+      const queue = [...names];
+      const worker = async () => {
+        while (queue.length) {
+          const name = queue.shift();
+          const data = await get(`https://registry.npmjs.org/${name.replace('/', '%2F')}`);
+          const latest = data && data['dist-tags'] && data['dist-tags'].latest;
+          const manifest = latest && data.versions ? data.versions[latest] || {} : {};
+          out[name] = {
+            date: latest && data.time && data.time[latest] ? data.time[latest].slice(0, 10) : null,
+            // How tightly it is tied to React Native: through its dependencies ('deps'; some only
+            // indirectly, e.g. react-native-elements peers on react-native-vector-icons), only by
+            // name ('name'), or not at all (null).
+            rnLink: ['peerDependencies', 'dependencies'].some((k) =>
+              Object.keys(manifest[k] || {}).some((d) => /^(react-native|expo)(-|$)|^@react-native(-community)?\//.test(d)),
+            )
+              ? 'deps'
+              : /react-native|^expo-/.test(name)
+                ? 'name'
+                : null,
+          };
+        }
+      };
+      await Promise.all(Array.from({ length: concurrency }, worker));
+      return out;
+    },
+
+    // Stable versions of a package, newest release line first.
+    async releaseLines(name, pick) {
+      // The abbreviated "install" document is a fraction of the full packument's size.
+      const data = await get(`https://registry.npmjs.org/${name}`, { Accept: 'application/vnd.npm.install-v1+json' });
+      if (!data || !data.versions) return null;
+      const stable = Object.keys(data.versions).filter((v) => /^\d+\.\d+\.\d+$/.test(v));
+      // The `latest` dist-tag is the authority: lines published above it are previews
+      // (Expo ships the next SDK's packages before tagging it). `pick` returns NaN for
+      // versions outside the release scheme; NaN would corrupt the sort.
+      const latest = data['dist-tags'].latest;
+      const top = pick(latest);
+      const lines = [...new Set(stable.map(pick))]
+        .filter((n) => Number.isFinite(n) && n <= top)
+        .sort((a, b) => b - a);
+      return { latest, lines };
+    },
+  };
+}

package/src/report-html.js

@@ -0,0 +1,87 @@
+import { SEVERITIES, countBySeverity } from './analyze.js';
+import { SITE_URL } from './config.js';
+
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[ch]);
+// Turns `code` spans from finding text into <code>.
+const rich = (s) => esc(s).replace(/`([^`]+)`/g, '<code>$1</code>');
+
+// A single self-contained file that can be emailed or attached to a ticket.
+// `brand` replaces NativeKeel branding with an agency's name.
+export function htmlReport(result, { brand = null, plan = null } = {}) {
+  const p = result.project;
+  const n = countBySeverity(result.findings);
+  const title = `${p.name || 'App'} health report`;
+  const sevLabel = { critical: 'Critical', high: 'High', medium: 'Medium', low: 'Low', info: 'Info' };
+  const arch = (v) => (v === true ? 'on' : v === false ? 'off' : 'default');
+
+  const rows = SEVERITIES.flatMap((sev) =>
+    result.findings
+      .filter((f) => f.severity === sev)
+      .map((f) => `<li class="f ${sev}"><span class="tag">${sevLabel[sev]}</span><div><strong>${rich(f.title)}</strong><p>${rich(f.detail)}</p></div></li>`),
+  ).join('\n');
+
+  const planHtml = plan
+    ? `<section><h2>Upgrade plan <small>scope: ${esc(plan.complexity.size)}</small></h2>${plan.phases
+        .map((ph, i) => `<h3>${i + 1}. ${esc(ph.title)}</h3><p class="why">${esc(ph.why)}</p><ul>${ph.steps.map((s) => `<li>${rich(s)}</li>`).join('')}</ul>`)
+        .join('')}</section>`
+    : '';
+
+  const footer = brand
+    ? `Prepared by ${esc(brand)} · ${esc(result.scannedAt.slice(0, 10))}`
+    : `Generated by <a href="${SITE_URL}">NativeKeel</a> · ${esc(result.scannedAt.slice(0, 10))}`;
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>
+:root{--bg:#f7f8fa;--card:#fff;--text:#16181d;--muted:#5f6673;--line:#e3e6eb;--critical:#c62828;--high:#b26a00;--medium:#8a6d00;--low:#6b7280;--info:#1e5fb4;--accent:#0b5d55}
+@media (prefers-color-scheme:dark){:root{--bg:#0f1115;--card:#171a20;--text:#e8eaee;--muted:#9aa1ad;--line:#2a2f38;--critical:#ff6b6b;--high:#f0a73a;--medium:#d9c24a;--low:#8b93a1;--info:#6aa7ff;--accent:#3cc4b4}}
+*{box-sizing:border-box}body{margin:0;background:var(--bg);color:var(--text);font:15px/1.55 system-ui,-apple-system,Segoe UI,Roboto,sans-serif}
+main{max-width:860px;margin:0 auto;padding:32px 16px 48px}
+h1{font-size:26px;margin:0 0 4px}h2{font-size:19px;margin:32px 0 12px}h2 small{font-weight:400;color:var(--muted);font-size:14px}h3{font-size:16px;margin:20px 0 4px}
+.meta{color:var(--muted);margin:0 0 20px}
+.stats{display:grid;grid-template-columns:repeat(4,1fr);gap:10px}
+.stat{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:12px}
+.stat b{display:block;font-size:24px}.stat span{color:var(--muted);font-size:13px}
+.stat.critical b{color:var(--critical)}.stat.high b{color:var(--high)}
+.facts{background:var(--card);border:1px solid var(--line);border-radius:10px;padding:12px 16px;margin-top:12px;display:flex;flex-wrap:wrap;gap:6px 24px;font-size:14px}
+ul.list{list-style:none;padding:0;margin:0;display:grid;gap:8px}
+.f{display:flex;gap:12px;background:var(--card);border:1px solid var(--line);border-left:4px solid var(--low);border-radius:8px;padding:10px 14px}
+.f p{margin:2px 0 0;color:var(--muted);font-size:14px}.f strong{overflow-wrap:anywhere}
+.tag{flex:none;font-size:12px;font-weight:600;text-transform:uppercase;letter-spacing:.03em;min-width:64px;padding-top:2px}
+.critical{border-left-color:var(--critical)}.critical .tag{color:var(--critical)}
+.high{border-left-color:var(--high)}.high .tag{color:var(--high)}
+.medium{border-left-color:var(--medium)}.medium .tag{color:var(--medium)}
+.low .tag{color:var(--low)}.info{border-left-color:var(--info)}.info .tag{color:var(--info)}
+code{font:13px ui-monospace,SFMono-Regular,Menlo,monospace;background:color-mix(in srgb,var(--line) 60%,transparent);padding:1px 4px;border-radius:4px;overflow-wrap:anywhere}
+.why{color:var(--muted);font-style:italic;margin:0 0 6px}
+footer{margin-top:40px;color:var(--muted);font-size:13px}a{color:var(--accent)}
+@media (max-width:560px){.stats{grid-template-columns:repeat(2,1fr)}.f{flex-direction:column;gap:4px}}
+</style>
+</head>
+<body><main>
+<h1>${esc(title)}</h1>
+<p class="meta">Scanned ${esc(result.scannedAt.slice(0, 16).replace('T', ' '))} UTC</p>
+<div class="stats">
+<div class="stat critical"><b>${n.critical}</b><span>critical</span></div>
+<div class="stat high"><b>${n.high}</b><span>high</span></div>
+<div class="stat"><b>${n.medium}</b><span>medium</span></div>
+<div class="stat"><b>${n.low}</b><span>low</span></div>
+</div>
+<div class="facts">
+${p.reactNative ? `<span>React Native <b>${esc(p.reactNative)}</b>${result.latest.reactNative ? ` (latest ${esc(result.latest.reactNative)})` : ''}</span>` : ''}
+${p.expo ? `<span>Expo SDK <b>${esc(p.expo.split('.')[0])}</b></span>` : ''}
+<span>New Architecture: Android <b>${arch(p.newArch.android)}</b>, iOS <b>${arch(p.newArch.ios)}</b></span>
+${p.android && p.android.targetSdk ? `<span>targetSdk <b>${p.android.targetSdk}</b></span>` : ''}
+<span>${result.deps.length} dependencies (${result.deps.filter((d) => d.native).length} native)</span>
+</div>
+<h2>Findings</h2>
+${result.findings.length ? `<ul class="list">${rows}</ul>` : '<p>No issues found.</p>'}
+${planHtml}
+<footer>${footer}</footer>
+</main></body></html>
+`;
+}