nativekeel 0.1.0

package/src/analyze.js

@@ -0,0 +1,360 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { cleanVersion, findPackageDir, installedVersion } from './project.js';
+import { createRegistry } from './registry.js';
+import { scanSecrets } from './secrets.js';
+import { nativeChecks } from './native.js';
+import { findUnused } from './usage.js';
+import { matchKnownIssues } from './known-issues.js';
+import { COMPAT, bestRange, checkCompat } from './compat.js';
+import { interopProblems } from './interop.js';
+import {
+  CRITICAL_EXPO_MAJORS_BEHIND,
+  CRITICAL_RN_MINORS_BEHIND,
+  NEW_ARCH_ONLY_MINOR,
+  RECENT_RELEASE_DAYS,
+  STALE_RELEASE_DAYS,
+  PLAY_TARGET_SDK,
+  REPLACEMENTS,
+  SUPPORTED_EXPO_MAJORS,
+  SUPPORTED_RN_MINORS,
+} from './rules.js';
+
+export const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
+
+const minorOf = (v) => Number(v.split('.')[1]);
+const majorOf = (v) => Number(v.split('.')[0]);
+// For 0.x packages the minor is the breaking-change line.
+const lineOf = (v) => {
+  const [maj, min] = v.split('.').map(Number);
+  return maj === 0 ? `0.${min}` : String(maj);
+};
+
+// react, react-native and @react-native/* move together with the React Native version; @babel/* and types are tooling.
+const isTracked = (name) =>
+  !['react-native', 'react', 'expo'].includes(name) &&
+  !name.startsWith('@react-native/') &&
+  !name.startsWith('@babel/') &&
+  !name.startsWith('@types/');
+
+function isNativeModule(root, name, dir) {
+  const base = findPackageDir(root, name);
+  if (base) {
+    if (fs.existsSync(path.join(base, 'android')) || fs.existsSync(path.join(base, 'ios'))) return true;
+    try {
+      return fs.readdirSync(base).some((f) => f.endsWith('.podspec'));
+    } catch {
+      return false;
+    }
+  }
+  // Without node_modules, trust React Native Directory's platform flags.
+  return !!(dir && (dir.ios || dir.android) && !dir.web);
+}
+
+// `offline: true` means the user asked for no network access (get returns nothing).
+export async function analyze(project, { get, now = new Date(), offline: forcedOffline = false } = {}) {
+  const registry = createRegistry(get);
+  const findings = [];
+  const add = (f) => findings.push(f);
+
+  const runtime = Object.keys(project.deps).filter(isTracked);
+  const devCandidates = Object.keys(project.devDeps || {}).filter((n) => isTracked(n) && !runtime.includes(n));
+  const [rn, expo, directory] = await Promise.all([
+    project.rnVersion ? registry.releaseLines('react-native', (v) => (v.startsWith('0.') ? minorOf(v) : NaN)) : null,
+    project.expoVersion ? registry.releaseLines('expo', majorOf) : null,
+    registry.directoryInfo([...runtime, ...devCandidates]),
+  ]);
+  // From devDependencies only native modules matter: they get autolinked into the app.
+  const devNative = devCandidates.filter((n) => isNativeModule(project.root, n, directory[n]));
+  const names = [...runtime, ...devNative];
+  const declaredRange = (n) => project.deps[n] || project.devDeps[n];
+  const latest = await registry.npmLatest(names);
+  const offline = forcedOffline || (!rn && !Object.keys(directory).length && !Object.values(latest).some(Boolean));
+  const warnings = [];
+  if (!project.hasNodeModules) {
+    warnings.push('node_modules not found: versions are read from package.json ranges and native detection is less accurate. Install dependencies for a precise report.');
+  }
+  if (!offline && project.rnVersion && !rn) warnings.push('Could not fetch React Native releases from npm; version and New Architecture checks were skipped. Run again.');
+  if (!offline && project.expoVersion && !expo) warnings.push('Could not fetch Expo releases from npm; the SDK check was skipped. Run again.');
+
+  // 1. React Native version support
+  const current = project.rnVersion;
+  if (rn && current) {
+    const behind = rn.lines[0] - minorOf(current);
+    if (behind >= SUPPORTED_RN_MINORS) {
+      add({
+        id: 'rn-unsupported',
+        severity: behind >= CRITICAL_RN_MINORS_BEHIND ? 'critical' : 'high',
+        area: 'react-native',
+        title: `React Native ${current} is no longer supported`,
+        detail: `Latest is ${rn.latest}. You are ${behind} minor versions behind; only the latest ${SUPPORTED_RN_MINORS} minors receive fixes.`,
+        fix: { kind: 'upgrade-rn', from: current, to: rn.latest },
+      });
+    } else if (behind > 0) {
+      add({
+        id: 'rn-behind',
+        severity: 'info',
+        area: 'react-native',
+        title: `React Native ${current} is still supported`,
+        detail: `Latest is ${rn.latest} (${behind} minor behind).`,
+        fix: { kind: 'upgrade-rn', from: current, to: rn.latest },
+      });
+    }
+
+    // 2. New Architecture
+    const off = ['android', 'ios'].filter((p) => project.newArch[p] === false);
+    if (minorOf(current) < NEW_ARCH_ONLY_MINOR && off.length && rn.lines[0] >= NEW_ARCH_ONLY_MINOR) {
+      add({
+        id: 'new-arch-disabled',
+        severity: 'critical',
+        area: 'new-architecture',
+        title: `New Architecture is disabled (${off.join(' + ')})`,
+        detail: `The legacy architecture was removed in 0.${NEW_ARCH_ONLY_MINOR}. This app cannot upgrade past 0.${NEW_ARCH_ONLY_MINOR - 1} until it migrates.`,
+        fix: { kind: 'enable-new-arch', platforms: off },
+      });
+    }
+  }
+
+  // 3. Expo SDK support
+  if (expo && project.expoVersion) {
+    const behind = expo.lines[0] - majorOf(project.expoVersion);
+    if (behind >= SUPPORTED_EXPO_MAJORS) {
+      add({
+        id: 'expo-unsupported',
+        severity: behind >= CRITICAL_EXPO_MAJORS_BEHIND ? 'critical' : 'high',
+        area: 'expo',
+        title: `Expo SDK ${majorOf(project.expoVersion)} is no longer supported`,
+        detail: `Latest is SDK ${expo.lines[0]}. Upgrade one SDK at a time with \`npx expo install expo@^<next> --fix\`.`,
+        fix: { kind: 'upgrade-expo', from: majorOf(project.expoVersion), to: expo.lines[0] },
+      });
+    } else if (behind > 0) {
+      add({
+        id: 'expo-behind',
+        severity: 'info',
+        area: 'expo',
+        title: `Expo SDK ${majorOf(project.expoVersion)} is still supported`,
+        detail: `Latest is SDK ${expo.lines[0]}.`,
+        fix: { kind: 'upgrade-expo', from: majorOf(project.expoVersion), to: expo.lines[0] },
+      });
+    }
+  }
+
+  // 4. Google Play target SDK
+  const target = project.android && project.android.targetSdk;
+  if (target) {
+    const today = now.toISOString().slice(0, 10);
+    const { updates, visibility } = PLAY_TARGET_SDK;
+    if (today >= visibility.since && target < visibility.minimum) {
+      add({
+        id: 'play-target-sdk-visibility',
+        severity: 'critical',
+        area: 'store',
+        title: `targetSdk ${target} hides the app from users on newer Android versions`,
+        detail: `Since ${visibility.since} Google Play requires API ${visibility.minimum}+ for published apps to stay visible, and API ${updates.minimum}+ to publish any update.`,
+        fix: { kind: 'target-sdk', from: target, to: updates.minimum },
+      });
+    } else if (today >= updates.since && target < updates.minimum) {
+      add({
+        id: 'play-target-sdk-updates',
+        severity: 'critical',
+        area: 'store',
+        title: `targetSdk ${target}: Google Play will reject your next update`,
+        detail: `Since ${updates.since} new apps and updates must target API ${updates.minimum}+ (extension possible until ${updates.extensionUntil}).`,
+        fix: { kind: 'target-sdk', from: target, to: updates.minimum },
+      });
+    }
+  }
+
+  // 5. Dependencies
+  // React Native Directory knows most packages, but its "unmaintained" flag can lag reality in
+  // both directions. For packages it does not know, or flags as unmaintained, the date of the
+  // latest npm release decides.
+  const recencyCandidates = names.filter((n) => !directory[n] || directory[n].unmaintained);
+  const published = forcedOffline ? {} : await registry.publishDates(recencyCandidates);
+  const daysSince = (date) => (date ? Math.floor((now - new Date(`${date}T00:00:00Z`)) / 86400000) : null);
+
+  const deps = [];
+  for (const name of names) {
+    const dir = directory[name];
+    const version = cleanVersion(installedVersion(project.root, name) || declaredRange(name));
+    const native = isNativeModule(project.root, name, dir);
+    const release = published[name] || {};
+    const age = daysSince(release.date);
+    const revived = !!(dir && dir.unmaintained && age !== null && age <= RECENT_RELEASE_DAYS);
+    const dep = {
+      name,
+      version,
+      latest: latest[name] || null,
+      native,
+      newArch: dir ? dir.newArchitecture : undefined,
+      unmaintained: !!(dir && dir.unmaintained) && !revived,
+      lastRelease: release.date || null,
+    };
+    deps.push(dep);
+
+    const noNewArch = native && dir && dir.newArchitecture === false;
+    // Only code that has to follow React Native or the OS goes stale; a finished JS utility does not.
+    const stale = !dep.unmaintained && !revived && age !== null && age > STALE_RELEASE_DAYS && (native || !!release.rnLink);
+    const alternatives = dir && dir.alternatives && dir.alternatives.length ? dir.alternatives : REPLACEMENTS[name] || [];
+    if (noNewArch || dep.unmaintained || stale) {
+      const problems = [
+        noNewArch && 'no New Architecture support',
+        dep.unmaintained && 'unmaintained',
+        stale && `no release since ${release.date.slice(0, 7)}`,
+      ].filter(Boolean);
+      const why = noNewArch
+        ? 'Likely upgrade blocker (it may still run through the interop layer). Plan a replacement or a maintained fork.'
+        : 'No fixes will come for future React Native, iOS or Android releases.';
+      add({
+        id: `dep-risk:${name}`,
+        severity: noNewArch || native ? 'high' : stale && !dep.unmaintained && release.rnLink === 'name' ? 'low' : 'medium',
+        area: 'dependency',
+        title: `${name}: ${problems.join(', ')}`,
+        detail: `${why}${alternatives.length ? ` Alternatives: ${alternatives.join(', ')}.` : ''}`,
+        fix: { kind: 'replace-dep', name, native, noNewArch, unmaintained: dep.unmaintained || stale, alternatives },
+      });
+    } else if (revived) {
+      add({
+        id: `dep-revived:${name}`,
+        severity: 'info',
+        area: 'dependency',
+        title: `${name}: marked unmaintained, but ${release.date} saw a new release`,
+        detail: 'React Native Directory still lists it as unmaintained. Maintenance may have resumed; check the changelog and issue tracker before replacing it.',
+      });
+    }
+    if (!noNewArch && !dep.unmaintained && !stale && version && dep.latest && lineOf(version) !== lineOf(dep.latest)) {
+      add({
+        id: `dep-major:${name}`,
+        severity: 'low',
+        area: 'dependency',
+        title: `${name} ${version} → ${dep.latest}`,
+        detail: 'Major version behind.',
+        fix: { kind: 'bump-dep', name, from: version, to: dep.latest, native },
+      });
+    }
+  }
+
+  // Unused runtime dependencies: removing them is cheaper than upgrading them.
+  const unused = new Set();
+  for (const u of findUnused(project)) {
+    unused.add(u.name);
+    add({
+      id: `unused:${u.name}`,
+      severity: u.native ? 'medium' : 'low',
+      area: 'dependency',
+      title: `${u.name} is installed but never used${u.native ? ' (native module)' : ''}`,
+      detail: `Not imported from JS, not referenced from native code, not required by another dependency.${u.native ? ' It still compiles into both apps and has to survive every upgrade.' : ''} Remove it.`,
+      fix: { kind: 'remove-dep', name: u.name, native: u.native },
+    });
+  }
+  // A package you are about to delete does not need upgrade advice.
+  for (let i = findings.length - 1; i >= 0; i--) {
+    const f = findings[i];
+    if (f.fix && ['replace-dep', 'bump-dep'].includes(f.fix.kind) && unused.has(f.fix.name)) findings.splice(i, 1);
+  }
+
+  // Known version-specific breakages, learned from real upgrades.
+  const newArchOn = project.newArch.android !== false && project.newArch.ios !== false && minorOf(current || '0.0') >= 76;
+  // The legacy architecture ends at 0.81, so any older app with it off has to migrate; this
+  // holds even when the latest release could not be fetched (offline).
+  const archOff = project.newArch.android === false || project.newArch.ios === false;
+  const newArchRequired =
+    findings.some((f) => f.id === 'new-arch-disabled') || (archOff && current && minorOf(current) < NEW_ARCH_ONLY_MINOR);
+  for (const { issue, dep } of matchKnownIssues({ deps, rnVersion: current, newArchOn, newArchRequired })) {
+    add({
+      id: `known:${issue.id}`,
+      severity: issue.severity,
+      area: 'dependency',
+      title: issue.title,
+      detail: `${issue.detail} (installed: ${dep.name} ${dep.version}; seen in: ${issue.source})`,
+      fix: { kind: 'known-issue', name: dep.name, title: issue.title, detail: issue.detail },
+    });
+  }
+
+  // Library ↔ React Native compatibility, from the libraries' own tables.
+  if (current) {
+    const rnMinor = minorOf(current);
+    for (const dep of deps.filter((d) => COMPAT[d.name])) {
+      const problem = checkCompat(dep.name, dep.version, rnMinor, newArchOn);
+      // Also check the architecture this app has to move to.
+      const ahead = !problem && newArchRequired ? checkCompat(dep.name, dep.version, rnMinor, true) : null;
+      if (!problem && !ahead) continue;
+      const best = bestRange(dep.name, rnMinor, problem ? newArchOn : true);
+      add({
+        id: `compat:${dep.name}`,
+        severity: problem ? 'high' : 'medium',
+        area: 'dependency',
+        title: problem || `${ahead} (needed for the New Architecture)`,
+        detail: `${best ? `Use ${dep.name} ${best.range} on React Native ${current}. ` : ''}Source: ${COMPAT[dep.name].source}.${COMPAT[dep.name].note ? ` ${COMPAT[dep.name].note}` : ''}`,
+        fix: { kind: 'compat', name: dep.name, range: best && best.range, forNewArch: !problem },
+      });
+    }
+  }
+
+  // Native modules that cannot load through the New Architecture interop layer (Android).
+  const androidNewArch = project.newArch.android !== false && minorOf(current || '0.0') >= 76;
+  if (androidNewArch || newArchRequired) {
+    for (const p of interopProblems(project, deps)) {
+      add({
+        id: `interop-job:${p.name}`,
+        severity: androidNewArch ? 'critical' : 'high',
+        area: 'new-architecture',
+        title: `${p.name} will not load on Android with the New Architecture (${p.methods.length} @ReactMethod${p.methods.length === 1 ? '' : 's'} return a coroutine Job)`,
+        detail: `${p.methods.slice(0, 4).join(', ')}${p.methods.length > 4 ? ', …' : ''} are written as \`fun x(...) = scope.launch { }\`. The interop layer only accepts void methods ("Unable to parse @ReactMethod ... unsupported return class: kotlinx.coroutines.Job"), so the whole module fails to load; if it is imported at startup the app shows a red screen. Patch the methods to return Unit (patch-package) or move to a version with a TurboModule spec.`,
+        fix: { kind: 'interop-job', name: p.name, methods: p.methods },
+      });
+    }
+  }
+
+  // 6. Native project: store requirements, built binaries, security settings
+  findings.push(...nativeChecks(project, { rnLatest: rn && rn.latest, now }));
+
+  // 7. Secrets
+  for (const s of scanSecrets(project.root)) {
+    const value = s.preview ? `Value ${s.preview}. ` : '';
+    const where = `${s.file}:${s.line}`;
+    if (s.inAppBundle) {
+      add({
+        id: `secret:${s.rule}:${s.file}`,
+        severity: 'critical',
+        area: 'secret',
+        title: `${s.label} shipped inside the app (${where})`,
+        detail: `${value}Anyone who downloads the app can extract it. Revoke it now, then move the call to a server.`,
+        fix: { kind: 'secret', label: s.label, file: s.file, line: s.line, bundled: true },
+      });
+    } else if (s.committed !== false) {
+      add({
+        id: `secret:${s.rule}:${s.file}`,
+        severity: 'high',
+        area: 'secret',
+        title: `${s.label} committed to the repository (${where})`,
+        detail: `${value}Not shipped in the app, but everyone with repo access has it and it stays in git history. Rotate it and load it from the environment instead.`,
+        fix: { kind: 'secret', label: s.label, file: s.file, line: s.line, bundled: false },
+      });
+    }
+  }
+
+  findings.sort((a, b) => SEVERITIES.indexOf(a.severity) - SEVERITIES.indexOf(b.severity));
+  return {
+    tool: 'nativekeel',
+    scannedAt: now.toISOString(),
+    project: {
+      name: project.name,
+      root: project.root,
+      reactNative: project.rnVersion,
+      expo: project.expoVersion,
+      managed: project.managed,
+      newArch: project.newArch,
+      android: project.android,
+    },
+    latest: { reactNative: rn && rn.latest, expo: expo && expo.latest },
+    offline,
+    offlineRequested: forcedOffline,
+    warnings,
+    deps,
+    findings,
+  };
+}
+
+export const countBySeverity = (findings) =>
+  Object.fromEntries(SEVERITIES.map((s) => [s, findings.filter((f) => f.severity === s).length]));

package/src/baseline.js

@@ -0,0 +1,23 @@
+import fs from 'node:fs';
+
+// A baseline is the list of finding ids a team has accepted. In CI only findings that are
+// not in the baseline fail the build, so an old app can adopt NativeKeel without fixing
+// everything on day one, and nothing new slips in afterwards.
+
+export function saveBaseline(file, result) {
+  const data = {
+    tool: 'nativekeel',
+    createdAt: result.scannedAt,
+    ids: [...new Set(result.findings.filter((f) => f.severity !== 'info').map((f) => f.id))].sort(),
+  };
+  fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`);
+  return data.ids.length;
+}
+
+export function applyBaseline(file, result) {
+  const data = JSON.parse(fs.readFileSync(file, 'utf8'));
+  const known = new Set(data.ids || []);
+  const findings = result.findings.filter((f) => !known.has(f.id));
+  const fixed = [...known].filter((id) => !result.findings.some((f) => f.id === id));
+  return { ...result, findings, baseline: { file, suppressed: result.findings.length - findings.length, fixed } };
+}

package/src/compare.js

@@ -0,0 +1,55 @@
+import { SEVERITIES, countBySeverity } from './analyze.js';
+
+// Compares two scans (from `--json`): what got fixed, what is new, how versions moved.
+// Used for monthly Care reports and before/after case studies.
+
+const arch = (a) => (a && a.android !== false && a.ios !== false ? 'on' : 'off');
+
+export function compareScans(before, after) {
+  const beforeIds = new Map(before.findings.map((f) => [f.id, f]));
+  const afterIds = new Map(after.findings.map((f) => [f.id, f]));
+  const notInfo = (f) => f.severity !== 'info';
+  return {
+    fixed: before.findings.filter((f) => notInfo(f) && !afterIds.has(f.id)),
+    added: after.findings.filter((f) => notInfo(f) && !beforeIds.has(f.id)),
+    counts: { before: countBySeverity(before.findings), after: countBySeverity(after.findings) },
+    versions: {
+      reactNative: [before.project.reactNative, after.project.reactNative],
+      expo: [before.project.expo, after.project.expo],
+      newArch: [arch(before.project.newArch), arch(after.project.newArch)],
+      dependencies: [before.deps.length, after.deps.length],
+      native: [before.deps.filter((d) => d.native).length, after.deps.filter((d) => d.native).length],
+    },
+    dates: [before.scannedAt, after.scannedAt],
+  };
+}
+
+export function compareToMarkdown(c, { title = 'Health report: before and after' } = {}) {
+  const row = (label, [a, b]) => (a === b || (a == null && b == null) ? null : `| ${label} | ${a ?? '–'} | ${b ?? '–'} |`);
+  const lines = [`### ${title}`, '', `${c.dates[0].slice(0, 10)} → ${c.dates[1].slice(0, 10)}`, '', '| | Before | After |', '|---|---|---|'];
+  lines.push(
+    ...[
+      row('React Native', c.versions.reactNative),
+      row('Expo SDK', c.versions.expo),
+      row('New Architecture', c.versions.newArch),
+      row('Dependencies', c.versions.dependencies),
+      row('Native modules', c.versions.native),
+    ].filter(Boolean),
+  );
+  for (const sev of SEVERITIES.filter((s) => s !== 'info')) {
+    lines.push(`| ${sev[0].toUpperCase()}${sev.slice(1)} findings | ${c.counts.before[sev]} | ${c.counts.after[sev]} |`);
+  }
+  lines.push('');
+  if (c.fixed.length) {
+    lines.push(`**Fixed (${c.fixed.length})**`, '');
+    for (const f of c.fixed) lines.push(`- ✅ ${f.title}`);
+    lines.push('');
+  }
+  if (c.added.length) {
+    lines.push(`**New (${c.added.length})**`, '');
+    for (const f of c.added) lines.push(`- ${f.severity === 'critical' || f.severity === 'high' ? '⚠️' : '•'} ${f.title}`);
+    lines.push('');
+  }
+  if (!c.fixed.length && !c.added.length) lines.push('No changes in findings.', '');
+  return `${lines.join('\n')}\n`;
+}

package/src/compat.js

@@ -0,0 +1,125 @@
+import { compareVersions } from './known-issues.js';
+
+// Which library versions work with which React Native versions, per architecture. Taken from
+// each library's own compatibility table; nothing here is guessed. Rows are version ranges
+// [from, to] (inclusive; `to` may be open) with the React Native minor range they support.
+// legacy: false means the range does not run on the old architecture at all.
+
+export const COMPAT = {
+  'react-native-screens': {
+    source: 'https://github.com/software-mansion/react-native-screens#support-for-fabric (checked 2026-10-03)',
+    newArch: [
+      { from: '4.0.0', to: '4.4.99', rnMin: 76 },
+      { from: '4.5.0', to: '4.13.99', rnMin: 77 },
+      { from: '4.14.0', to: '4.18.99', rnMin: 79 },
+      { from: '4.19.0', to: '4.24.99', rnMin: 81 },
+      { from: '4.25.0', to: '4.25.99', rnMin: 82 },
+      { from: '4.26.0', rnMin: 84 },
+    ],
+    legacy: [
+      { from: '4.0.0', to: '4.4.99', rnMin: 72 },
+      { from: '4.5.0', to: '4.8.99', rnMin: 74 },
+      { from: '4.9.0', to: '4.13.99', rnMin: 76 },
+      { from: '4.14.0', to: '4.18.99', rnMin: 79 },
+      { from: '4.19.0', to: '4.24.99', rnMin: 80 },
+      { from: '4.25.0', unsupported: true },
+    ],
+  },
+  'react-native-gesture-handler': {
+    source: 'https://github.com/software-mansion/react-native-gesture-handler#gesture-handler-2 (checked 2026-10-03)',
+    note: 'Gesture Handler supports the three latest React Native minors; the table gives minimums.',
+    newArch: [
+      { from: '2.18.0', to: '2.20.99', rnMin: 73 },
+      { from: '2.21.0', to: '2.23.99', rnMin: 74 },
+      { from: '2.24.0', to: '2.24.99', rnMin: 75 },
+      { from: '2.25.0', to: '2.25.99', rnMin: 76 },
+      { from: '2.26.0', to: '2.27.99', rnMin: 78 },
+      { from: '2.28.0', to: '2.31.99', rnMin: 79 },
+      { from: '2.32.0', to: '2.99.99', rnMin: 84 },
+      { from: '3.0.0', rnMin: 82 },
+    ],
+    legacy: [
+      { from: '2.18.0', to: '2.20.99', rnMin: 73 },
+      { from: '2.21.0', to: '2.23.99', rnMin: 74 },
+      { from: '2.24.0', to: '2.24.99', rnMin: 75 },
+      { from: '2.25.0', to: '2.25.99', rnMin: 76 },
+      { from: '2.26.0', to: '2.27.99', rnMin: 78 },
+      { from: '2.28.0', to: '2.31.99', rnMin: 79 },
+      { from: '2.32.0', to: '2.99.99', rnMin: 84 },
+    ],
+  },
+  'react-native-reanimated': {
+    source: 'https://docs.swmansion.com/react-native-reanimated/docs/guides/compatibility/ and /docs/3.x/guides/compatibility/ (checked 2026-10-03)',
+    newArch: [
+      { from: '3.0.0', to: '3.0.99', rnMin: 71, rnMax: 71 },
+      { from: '3.1.0', to: '3.5.99', rnMin: 72, rnMax: 72 },
+      { from: '3.6.0', to: '3.8.99', rnMin: 72, rnMax: 73 },
+      { from: '3.9.0', to: '3.14.99', rnMin: 74, rnMax: 74 },
+      { from: '3.15.0', to: '3.15.99', rnMin: 74, rnMax: 75 },
+      { from: '3.16.0', to: '3.16.99', rnMin: 74, rnMax: 77 },
+      { from: '3.17.0', to: '3.17.99', rnMin: 75, rnMax: 79 },
+      { from: '3.18.0', to: '3.18.99', rnMin: 75, rnMax: 80 },
+      { from: '3.19.0', to: '3.19.99', rnMin: 78, rnMax: 81 },
+      { from: '4.0.0', to: '4.1.99', rnMin: 78, rnMax: 81 },
+      { from: '4.2.0', to: '4.3.99', rnMin: 80, rnMax: 84 },
+      { from: '4.4.0', to: '4.5.99', rnMin: 83, rnMax: 86 },
+      { from: '4.6.0', to: '4.6.99', rnMin: 83, rnMax: 88 },
+      { from: '4.7.0', to: '4.8.99', rnMin: 86, rnMax: 88 },
+    ],
+    legacy: [
+      { from: '3.0.0', to: '3.2.99', rnMin: 63, rnMax: 71 },
+      { from: '3.3.0', to: '3.4.99', rnMin: 63, rnMax: 72 },
+      { from: '3.5.0', to: '3.5.99', rnMin: 66, rnMax: 71 },
+      { from: '3.6.0', to: '3.8.99', rnMin: 66, rnMax: 72 },
+      { from: '3.9.0', to: '3.15.99', rnMin: 70, rnMax: 73 },
+      { from: '3.16.0', to: '3.16.99', rnMin: 71, rnMax: 77 },
+      { from: '3.17.0', to: '3.17.99', rnMin: 73, rnMax: 79 },
+      { from: '3.18.0', to: '3.18.99', rnMin: 73, rnMax: 80 },
+      { from: '3.19.0', to: '3.19.99', rnMin: 77, rnMax: 81 },
+      { from: '4.0.0', unsupported: true },
+    ],
+    note: 'Reanimated 4 also needs react-native-worklets; Reanimated 3.x is no longer actively maintained.',
+  },
+};
+
+const inRange = (version, row) =>
+  compareVersions(version, row.from) >= 0 && (!row.to || compareVersions(version, row.to) <= 0);
+
+const rnLabel = (row) => (row.rnMax ? `0.${row.rnMin}–0.${row.rnMax}` : `0.${row.rnMin}+`);
+function versionLabel(row) {
+  const from = row.from.replace(/\.0$/, '');
+  if (!row.to) return `${from}+`;
+  const to = row.to.replace(/\.99$/, '');
+  return from === to ? `${from}.x` : `${from}–${to}.x`;
+}
+
+// Problem with the installed version on this React Native minor and architecture, or null.
+export function checkCompat(pkg, version, rnMinor, newArch) {
+  const table = COMPAT[pkg];
+  if (!table || !version || rnMinor == null) return null;
+  const rows = newArch ? table.newArch : table.legacy;
+  const row = rows.find((r) => inRange(version, r));
+  if (!row) return null; // older than the table covers: no claim
+  if (row.unsupported) return `${pkg} ${version} does not support the ${newArch ? 'New' : 'legacy'} Architecture`;
+  if (rnMinor < row.rnMin || (row.rnMax && rnMinor > row.rnMax)) {
+    return `${pkg} ${version} supports React Native ${rnLabel(row)}${newArch ? '' : ' on the legacy architecture'}, not 0.${rnMinor}`;
+  }
+  return null;
+}
+
+// The newest version range of `pkg` that supports this React Native minor and architecture.
+// With `major`, only ranges of that major version (to avoid a major migration in a hop).
+export function bestRange(pkg, rnMinor, newArch, { major = null } = {}) {
+  const table = COMPAT[pkg];
+  if (!table) return null;
+  const rows = (newArch ? table.newArch : table.legacy).filter(
+    (r) =>
+      !r.unsupported &&
+      rnMinor >= r.rnMin &&
+      (!r.rnMax || rnMinor <= r.rnMax) &&
+      (major === null || Number(r.from.split('.')[0]) === major),
+  );
+  if (!rows.length) return null;
+  const best = rows.sort((a, b) => compareVersions(b.from, a.from))[0];
+  return { range: versionLabel(best), from: best.from, to: best.to || null };
+}

package/src/config.js

@@ -0,0 +1,3 @@
+// Public contact points shown in reports and the CLI. Change here only.
+export const SITE_URL = 'https://nativekeel.com';
+export const CONTACT_EMAIL = 'hello@nativekeel.com';