nativekeel 0.1.0

package/src/report-md.js

@@ -0,0 +1,42 @@
+import { SEVERITIES, countBySeverity } from './analyze.js';
+import { SITE_URL } from './config.js';
+
+// Markdown for pull request comments and issue trackers.
+const ICON = { critical: '🔴', high: '🟠', medium: '🟡', low: '⚪', info: 'ℹ️' };
+const cell = (s) => String(s).replace(/\|/g, '\\|').replace(/\n/g, ' ');
+
+export function markdownReport(result, { verbose = false } = {}) {
+  const p = result.project;
+  const n = countBySeverity(result.findings);
+  const lines = [
+    `### NativeKeel health report${p.name ? `: ${p.name}` : ''}`,
+    '',
+    [
+      p.reactNative && `React Native **${p.reactNative}**${result.latest.reactNative ? ` (latest ${result.latest.reactNative})` : ''}`,
+      p.expo && `Expo SDK **${p.expo.split('.')[0]}**`,
+      `New Architecture: Android ${p.newArch.android === false ? '**off**' : p.newArch.android ? 'on' : 'default'}, iOS ${p.newArch.ios === false ? '**off**' : p.newArch.ios ? 'on' : 'default'}`,
+    ].filter(Boolean).join(' · '),
+    '',
+    `${ICON.critical} ${n.critical} critical · ${ICON.high} ${n.high} high · ${ICON.medium} ${n.medium} medium · ${ICON.low} ${n.low} low`,
+    '',
+  ];
+
+  const main = result.findings.filter((f) => ['critical', 'high', 'medium'].includes(f.severity));
+  if (main.length) {
+    lines.push('| | Finding | Details |', '|---|---|---|');
+    for (const sev of SEVERITIES) {
+      for (const f of main.filter((x) => x.severity === sev)) lines.push(`| ${ICON[sev]} | ${cell(f.title)} | ${cell(f.detail)} |`);
+    }
+    lines.push('');
+  }
+  const low = result.findings.filter((f) => f.severity === 'low');
+  if (low.length) {
+    lines.push(`<details><summary>${low.length} low-priority findings</summary>`, '');
+    for (const f of verbose ? low : low.slice(0, 50)) lines.push(`- ${f.title}`);
+    if (!verbose && low.length > 50) lines.push(`- … and ${low.length - 50} more`);
+    lines.push('', '</details>', '');
+  }
+  if (!result.findings.some((f) => f.severity !== 'info')) lines.push('✅ Nothing to fix.', '');
+  lines.push(`<sub>Generated by [NativeKeel](${SITE_URL}) · \`npx nativekeel plan\` for a step-by-step upgrade plan</sub>`);
+  return `${lines.join('\n')}\n`;
+}

package/src/report-sarif.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { SITE_URL } from './config.js';
+
+// SARIF 2.1.0 for GitHub code scanning: findings show up on the exact line in pull requests.
+// https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+
+const LEVEL = { critical: 'error', high: 'error', medium: 'warning', low: 'note', info: 'note' };
+
+// Where a finding lives: its own file/line when known, otherwise the package.json line that
+// declares the dependency, otherwise the top of package.json.
+function locate(result, finding, pkgLines) {
+  const fix = finding.fix || {};
+  if (fix.file) return { uri: fix.file, line: fix.line || 1 };
+  const name = fix.name || (finding.id.includes(':') ? finding.id.split(':').slice(1).join(':') : null);
+  if (name) {
+    const i = pkgLines.findIndex((l) => l.includes(`"${name}"`));
+    if (i >= 0) return { uri: 'package.json', line: i + 1 };
+  }
+  if (finding.id.startsWith('ios-ats:')) return { uri: finding.id.slice('ios-ats:'.length), line: 1 };
+  return { uri: 'package.json', line: 1 };
+}
+
+export function sarifReport(result, { version = '0.0.0' } = {}) {
+  let pkgLines = [];
+  try {
+    pkgLines = fs.readFileSync(path.join(result.project.root, 'package.json'), 'utf8').split('\n');
+  } catch {
+    pkgLines = [];
+  }
+  const findings = result.findings.filter((f) => f.severity !== 'info');
+  const ruleIds = [...new Set(findings.map((f) => f.id.split(':')[0]))].sort();
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'NativeKeel',
+            version,
+            informationUri: SITE_URL,
+            rules: ruleIds.map((id) => ({ id, name: id, shortDescription: { text: id.replace(/-/g, ' ') } })),
+          },
+        },
+        results: findings.map((f) => {
+          const loc = locate(result, f, pkgLines);
+          return {
+            ruleId: f.id.split(':')[0],
+            level: LEVEL[f.severity],
+            message: { text: `${f.title}. ${f.detail}` },
+            locations: [{ physicalLocation: { artifactLocation: { uri: loc.uri }, region: { startLine: loc.line } } }],
+            // Stable across runs so code scanning tracks one alert per finding.
+            partialFingerprints: { nativekeelId: f.id },
+            properties: { severity: f.severity, area: f.area },
+          };
+        }),
+      },
+    ],
+  };
+}

package/src/report-text.js

@@ -0,0 +1,72 @@
+import { SEVERITIES, countBySeverity } from './analyze.js';
+import { SITE_URL } from './config.js';
+
+export function textReport(result, { color = true, verbose = false } = {}) {
+  const paint = (code) => (s) => (color ? `\x1b[${code}m${s}\x1b[0m` : s);
+  const c = { red: paint('31'), yellow: paint('33'), blue: paint('34'), gray: paint('90'), bold: paint('1'), green: paint('32') };
+  const label = {
+    critical: c.red('✖ CRITICAL'),
+    high: c.yellow('▲ HIGH    '),
+    medium: c.yellow('● MEDIUM  '),
+    low: c.gray('· LOW     '),
+    info: c.blue('ℹ INFO    '),
+  };
+  const indent = '           ';
+  const out = [];
+  const p = result.project;
+  const arch = (v) => (v === true ? c.green('on') : v === false ? c.red('off') : c.gray('default'));
+
+  out.push('');
+  out.push(`${c.bold('NativeKeel health report')}  ${p.name || ''}`);
+  if (p.reactNative) out.push(`React Native ${p.reactNative}${result.latest.reactNative ? c.gray(` (latest ${result.latest.reactNative})`) : ''}`);
+  if (p.expo) out.push(`Expo SDK ${p.expo.split('.')[0]}${p.managed ? ' (managed)' : ''}${result.latest.expo ? c.gray(` (latest SDK ${result.latest.expo.split('.')[0]})`) : ''}`);
+  out.push(`New Architecture  android: ${arch(p.newArch.android)}  ios: ${arch(p.newArch.ios)}`);
+  if (p.android && p.android.targetSdk) out.push(`Android targetSdk ${p.android.targetSdk}`);
+  out.push(`Dependencies: ${result.deps.length} (${result.deps.filter((d) => d.native).length} native)`);
+  for (const w of result.warnings) out.push(c.yellow(`! ${w}`));
+  if (result.offlineRequested) out.push(c.gray('Offline mode: no network requests were made. Version and package checks need the network.'));
+  else if (result.offline) out.push(c.yellow('! Could not reach npm or React Native Directory. Only local checks (secrets, settings) ran.'));
+  out.push('');
+
+  for (const sev of SEVERITIES) {
+    const group = result.findings.filter((f) => f.severity === sev);
+    if (!group.length) continue;
+    if (sev === 'low') {
+      // Outdated packages are many and alike: list them compactly. Everything else gets a full entry.
+      const bumps = group.filter((f) => f.id.startsWith('dep-major:'));
+      for (const f of group.filter((x) => !x.id.startsWith('dep-major:'))) {
+        out.push(`${label.low} ${c.bold(f.title)}`);
+        out.push(c.gray(indent + f.detail));
+      }
+      if (bumps.length) {
+        const shown = verbose ? bumps : bumps.slice(0, 8);
+        out.push(`${label.low} ${bumps.length} package${bumps.length === 1 ? ' is' : 's are'} a major version behind:`);
+        out.push(c.gray(shown.map((f) => indent + f.title).join('\n')));
+        if (bumps.length > shown.length) out.push(c.gray(`${indent}… and ${bumps.length - shown.length} more (run with --verbose)`));
+      }
+      out.push('');
+      continue;
+    }
+    for (const f of group) {
+      out.push(`${label[sev]} ${c.bold(f.title)}`);
+      out.push(c.gray(indent + f.detail));
+    }
+    out.push('');
+  }
+
+  if (result.baseline) {
+    out.push(c.gray(`Baseline ${result.baseline.file}: ${result.baseline.suppressed} known findings hidden${result.baseline.fixed.length ? `, ${result.baseline.fixed.length} fixed since` : ''}.`));
+  }
+  const n = countBySeverity(result.findings);
+  out.push(`${c.bold('Summary')}  ${c.red(`${n.critical} critical`)} · ${c.yellow(`${n.high} high`)} · ${n.medium} medium · ${n.low} low`);
+
+  if (n.critical + n.high > 0) {
+    out.push('');
+    out.push(`Next: ${c.bold('npx nativekeel plan')} writes a step-by-step upgrade plan.`);
+    out.push(c.gray(`No time to do it yourself? Fixed-price upgrades: ${SITE_URL}/#services`));
+  } else if (!result.findings.length) {
+    out.push(c.green('Nothing to fix. This app is in good shape.'));
+  }
+  out.push('');
+  return out.join('\n');
+}

package/src/rules.js

@@ -0,0 +1,59 @@
+// Curated knowledge that the public registries do not provide.
+// Every entry here is a claim we make to users, so keep it short, sourced and dated.
+
+// The React Native team supports the latest minor and the two before it.
+// https://github.com/reactwg/react-native-releases/blob/main/docs/support.md
+export const SUPPORTED_RN_MINORS = 3;
+
+// Out of support is a risk, not an outage. It becomes critical once the gap is about a year
+// of releases (roughly six minors), when upgrades turn into projects.
+export const CRITICAL_RN_MINORS_BEHIND = 6;
+
+// First React Native minor where the legacy architecture is removed.
+export const NEW_ARCH_ONLY_MINOR = 82;
+
+// Expo ships about three SDKs a year and fixes only recent ones.
+export const SUPPORTED_EXPO_MAJORS = 3;
+export const CRITICAL_EXPO_MAJORS_BEHIND = 5;
+
+// Google Play target API level policy.
+// https://support.google.com/googleplay/android-developer/answer/11926878
+export const PLAY_TARGET_SDK = {
+  checkedAt: '2026-10-03',
+  // New apps and app updates
+  updates: { minimum: 36, since: '2026-08-31', extensionUntil: '2026-11-01' },
+  // Already published apps stay visible to users on newer Android versions only above this
+  visibility: { minimum: 35, since: '2026-08-31' },
+};
+
+// Google Play 16 KB memory page size requirement for apps targeting Android 15+.
+// https://android-developers.googleblog.com/2025/05/prepare-play-apps-for-devices-with-16kb-page-size.html
+// React Native supports 16 KB pages from 0.77.
+export const PAGE_SIZE_16K = { since: '2025-11-01', extensionUntil: '2026-05-31', firstRnMinor: 77 };
+
+// Minimum OS versions of current React Native (since 0.76).
+// https://reactnative.dev/blog/2024/10/23/release-0.76-new-architecture
+export const PLATFORM_MINIMUMS = { androidMinSdk: 24, iosMin: 15.1 };
+
+// A package with no npm release for this long will not follow React Native, iOS or Android changes.
+export const STALE_RELEASE_DAYS = 730;
+// A release this recent overrides an "unmaintained" flag that may be out of date.
+export const RECENT_RELEASE_DAYS = 180;
+
+// Replacement advice for native modules we have seen block upgrades.
+// Only used when React Native Directory has no alternatives listed.
+export const REPLACEMENTS = {
+  'react-native-fast-image': ['expo-image', '@d11/react-native-fast-image'],
+  'react-native-fs': ['@dr.pogodin/react-native-fs', 'expo-file-system'],
+  '@react-native-community/push-notification-ios': ['@react-native-firebase/messaging', 'expo-notifications'],
+  'react-native-keyboard-aware-scroll-view': ['react-native-keyboard-controller'],
+  'react-native-splash-screen': ['react-native-bootsplash', 'expo-splash-screen'],
+  'react-native-camera': ['react-native-vision-camera', 'expo-camera'],
+  'react-native-sqlite-storage': ['op-sqlite', 'expo-sqlite'],
+  'react-native-code-push': ['expo-updates'],
+  // react-native-elements was renamed to @rneui, which in turn is continued by @rn-vui.
+  'react-native-elements': ['@rn-vui/themed'],
+};
+
+export const UPGRADE_HELPER_URL = (from, to) =>
+  `https://react-native-community.github.io/upgrade-helper/?from=${from}&to=${to}`;

package/src/secrets.js

@@ -0,0 +1,98 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'Pods', 'build', '.gradle', 'DerivedData', '.expo', 'dist', 'coverage']);
+const EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.json', '.plist', '.xml', '.gradle', '.properties', '.env', '.m', '.mm', '.swift', '.kt', '.java']);
+const MAX_FILE_BYTES = 1024 * 1024;
+
+// Folders that hold server-side code: never bundled into the app, but still a leak if committed.
+const SERVER_DIRS = new Set(['functions', 'server', 'backend', 'api', 'cloud-functions', 'scripts']);
+
+// Only patterns that are almost never false positives. The `v` group is the secret value itself.
+const RULES = [
+  { id: 'aws-access-key', label: 'AWS access key ID', re: /\b(?<v>(?:AKIA|ASIA)[0-9A-Z]{16})\b/g },
+  { id: 'aws-secret-key', label: 'AWS secret access key', re: /secretAccessKey["']?\s*[:=]\s*["'](?<v>[A-Za-z0-9/+]{40})["']/g },
+  { id: 'private-key', label: 'Private key', re: /-----BEGIN (?:RSA |EC |OPENSSH |DSA )?PRIVATE KEY-----/g },
+  { id: 'stripe-secret', label: 'Stripe secret key', re: /\bsk_live_[0-9a-zA-Z]{20,}\b/g },
+  { id: 'openai-key', label: 'OpenAI API key', re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}\b/g },
+  { id: 'anthropic-key', label: 'Anthropic API key', re: /\bsk-ant-[A-Za-z0-9_-]{32,}\b/g },
+  { id: 'github-token', label: 'GitHub token', re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/g },
+  { id: 'slack-token', label: 'Slack token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g },
+  { id: 'sendgrid-key', label: 'SendGrid API key', re: /\b(?<v>SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43})\b/g },
+  { id: 'twilio-key', label: 'Twilio API key', re: /\b(?<v>SK[0-9a-fA-F]{32})\b/g },
+  { id: 'google-oauth-secret', label: 'Google OAuth client secret', re: /\b(?<v>GOCSPX-[A-Za-z0-9_-]{28})\b/g },
+  { id: 'mailchimp-key', label: 'Mailchimp API key', re: /\b(?<v>[0-9a-f]{32}-us\d{1,2})\b/g },
+  { id: 'shopify-token', label: 'Shopify access token', re: /\b(?<v>shp(?:at|ca|pa|ss)_[a-fA-F0-9]{32})\b/g },
+  // Supabase anon keys are public by design; the service_role key bypasses row-level security.
+  // Both are JWTs, so decode the payload and only report the service role.
+  {
+    id: 'supabase-service-role',
+    label: 'Supabase service_role key',
+    re: /\b(?<v>eyJ[A-Za-z0-9_-]{10,}\.(?<payload>eyJ[A-Za-z0-9_-]{10,})\.[A-Za-z0-9_-]{20,})\b/g,
+    validate: (m) => {
+      try {
+        return JSON.parse(Buffer.from(m.groups.payload, 'base64url').toString('utf8')).role === 'service_role';
+      } catch {
+        return false;
+      }
+    },
+  },
+];
+
+export function mask(value) {
+  if (value.length <= 8) return '****';
+  return `${value.slice(0, 4)}…${value.slice(-2)}`;
+}
+
+function* walk(dir) {
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name)) yield* walk(path.join(dir, e.name));
+    } else if (EXTENSIONS.has(path.extname(e.name)) || e.name.startsWith('.env')) {
+      yield path.join(dir, e.name);
+    }
+  }
+}
+
+function gitTrackedFiles(root) {
+  const res = spawnSync('git', ['ls-files'], { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  return res.status === 0 ? new Set(res.stdout.split('\n')) : null;
+}
+
+export function scanSecrets(root) {
+  const findings = [];
+  const tracked = gitTrackedFiles(root);
+  for (const file of walk(root)) {
+    let text;
+    try {
+      if (fs.statSync(file).size > MAX_FILE_BYTES) continue;
+      text = fs.readFileSync(file, 'utf8');
+    } catch {
+      continue;
+    }
+    for (const rule of RULES) {
+      for (const m of text.matchAll(rule.re)) {
+        if (rule.validate && !rule.validate(m)) continue;
+        const rel = path.relative(root, file);
+        const value = m.groups && m.groups.v;
+        findings.push({
+          rule: rule.id,
+          label: rule.label,
+          file: rel,
+          line: text.slice(0, m.index).split('\n').length,
+          preview: value ? mask(value) : null,
+          inAppBundle: !SERVER_DIRS.has(rel.split(path.sep)[0]),
+          committed: tracked ? tracked.has(rel.split(path.sep).join('/')) : null,
+        });
+      }
+    }
+  }
+  return findings;
+}

package/src/usage.js

@@ -0,0 +1,127 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { findPackageDir } from './project.js';
+
+// Finds runtime dependencies that nothing uses. A package only counts as unused when it is
+// (1) never imported from JS/TS, (2) not referenced from native code, (3) not required by
+// another dependency (e.g. @rneui/themed needs @rneui/base even if the app never imports it),
+// and (4) not mentioned in config files or package.json scripts. Removing unused native
+// modules is the cheapest way to shrink an upgrade.
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'Pods', 'build', '.gradle', 'DerivedData', '.expo', 'dist', 'coverage', 'vendor']);
+const JS_EXT = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+const NATIVE_EXT = new Set(['.m', '.mm', '.h', '.swift', '.java', '.kt', '.gradle', '.kts', '.xml', '.plist']);
+const MAX_FILE_BYTES = 1024 * 1024;
+
+// Packages that are used without being imported.
+const IMPLICIT = [
+  /^(react|react-native|expo|react-dom)$/,
+  /^@babel\//,
+  /^@types\//,
+  /babel-plugin|babel-preset|eslint|prettier|typescript|metro/,
+  /^@react-native\//, // versioned with React Native, used by the build
+  /^@react-native-community\/cli/,
+  /^react-native-vector-icons$/, // fonts linked by the build
+];
+
+function walk(dir, exts, out = []) {
+  let list;
+  try {
+    list = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of list) {
+    if (e.isDirectory()) {
+      if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(path.join(dir, e.name), exts, out);
+    } else if (exts.has(path.extname(e.name))) {
+      out.push(path.join(dir, e.name));
+    }
+  }
+  return out;
+}
+
+const readSmall = (file) => {
+  try {
+    return fs.statSync(file).size > MAX_FILE_BYTES ? '' : fs.readFileSync(file, 'utf8');
+  } catch {
+    return '';
+  }
+};
+
+// 'lodash/fp' -> 'lodash', '@scope/pkg/sub' -> '@scope/pkg'
+export function packageOf(spec) {
+  if (!spec || spec.startsWith('.') || spec.startsWith('/')) return null;
+  const parts = spec.split('/');
+  return spec.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+
+export function importedPackages(text) {
+  const found = new Set();
+  const re = /(?:\bfrom\s*|\bimport\s*\(?\s*|\brequire\s*\(\s*|\bjest\.(?:mock|requireActual)\s*\(\s*)['"]([^'"\n]+)['"]/g;
+  for (const m of text.matchAll(re)) {
+    const pkg = packageOf(m[1]);
+    if (pkg) found.add(pkg);
+  }
+  return found;
+}
+
+// Names a package is known by in native code: its podspec module and its Android namespace.
+function nativeTokens(root, name) {
+  const dir = findPackageDir(root, name);
+  if (!dir) return [];
+  const tokens = [];
+  try {
+    for (const f of fs.readdirSync(dir)) if (f.endsWith('.podspec')) tokens.push(f.replace(/\.podspec$/, ''));
+  } catch {
+    // no podspec
+  }
+  const manifest = readSmall(path.join(dir, 'android', 'src', 'main', 'AndroidManifest.xml'));
+  const gradle = readSmall(path.join(dir, 'android', 'build.gradle')) + readSmall(path.join(dir, 'android', 'build.gradle.kts'));
+  const pkg = manifest.match(/package="([\w.]+)"/) || gradle.match(/namespace\s*=?\s*["']([\w.]+)["']/);
+  if (pkg) tokens.push(pkg[1]);
+  return tokens.filter((t) => t.length >= 5);
+}
+
+export function findUnused(project) {
+  if (!project.hasNodeModules) return [];
+  const root = project.root;
+  const names = Object.keys(project.deps).filter((n) => !IMPLICIT.some((re) => re.test(n)));
+  if (!names.length) return [];
+
+  const used = new Set();
+  for (const file of walk(root, JS_EXT)) for (const p of importedPackages(readSmall(file))) used.add(p);
+
+  // Config and scripts: babel/metro/app config plugins, CLI tools in scripts.
+  const pkgText = readSmall(path.join(root, 'package.json'));
+  const pkgJson = JSON.parse(pkgText || '{}');
+  const configText = [
+    JSON.stringify(pkgJson.scripts || {}),
+    JSON.stringify(pkgJson.jest || {}),
+    readSmall(path.join(root, 'app.json')),
+    readSmall(path.join(root, 'app.config.js')),
+    readSmall(path.join(root, 'app.config.ts')),
+    readSmall(path.join(root, 'react-native.config.js')),
+  ].join('\n');
+
+  // Required by another dependency (peer or regular).
+  const requiredByOthers = new Set();
+  for (const other of Object.keys(project.deps)) {
+    const dir = findPackageDir(root, other);
+    if (!dir) continue;
+    try {
+      const m = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+      for (const k of ['peerDependencies', 'dependencies']) for (const d of Object.keys(m[k] || {})) requiredByOthers.add(d);
+    } catch {
+      // unreadable manifest
+    }
+  }
+
+  const candidates = names.filter((n) => !used.has(n) && !requiredByOthers.has(n) && !configText.includes(n));
+  if (!candidates.length) return [];
+
+  const nativeText = ['ios', 'android'].flatMap((d) => walk(path.join(root, d), NATIVE_EXT)).map(readSmall).join('\n');
+  return candidates
+    .filter((n) => !nativeText.includes(n) && !nativeTokens(root, n).some((t) => nativeText.includes(t)))
+    .map((name) => ({ name, native: nativeTokens(root, name).length > 0 }));
+}