nativekeel 0.1.0

package/src/elf-align.js

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+
+// Checks native libraries inside a built APK/AAB for 16 KB page alignment, the same thing
+// Google's check_elf_alignment.sh does: every PT_LOAD segment of every 64-bit .so must be
+// aligned to at least 16 KB. Pure Node: a minimal ZIP reader plus an ELF header parser.
+
+const PAGE_16K = 16384;
+const ABIS_64 = ['arm64-v8a', 'x86_64'];
+
+function readZipEntries(buf) {
+  // End of central directory record is in the last 64 KB (+22 bytes).
+  const min = Math.max(0, buf.length - 65557);
+  let eocd = -1;
+  for (let i = buf.length - 22; i >= min; i--) {
+    if (buf.readUInt32LE(i) === 0x06054b50) {
+      eocd = i;
+      break;
+    }
+  }
+  if (eocd < 0) throw new Error('not a zip file');
+  let count = buf.readUInt16LE(eocd + 10);
+  let cdOffset = buf.readUInt32LE(eocd + 16);
+
+  // ZIP64: large APKs/AABs may need the ZIP64 end of central directory.
+  if (cdOffset === 0xffffffff || count === 0xffff) {
+    const locator = eocd - 20;
+    if (locator >= 0 && buf.readUInt32LE(locator) === 0x07064b50) {
+      const z64 = Number(buf.readBigUInt64LE(locator + 8));
+      count = Number(buf.readBigUInt64LE(z64 + 32));
+      cdOffset = Number(buf.readBigUInt64LE(z64 + 48));
+    }
+  }
+
+  const entries = [];
+  let p = cdOffset;
+  for (let i = 0; i < count; i++) {
+    if (buf.readUInt32LE(p) !== 0x02014b50) break;
+    const method = buf.readUInt16LE(p + 10);
+    let compSize = buf.readUInt32LE(p + 20);
+    let size = buf.readUInt32LE(p + 24);
+    const nameLen = buf.readUInt16LE(p + 28);
+    const extraLen = buf.readUInt16LE(p + 30);
+    const commentLen = buf.readUInt16LE(p + 32);
+    let localOffset = buf.readUInt32LE(p + 42);
+    const name = buf.toString('utf8', p + 46, p + 46 + nameLen);
+
+    // ZIP64 extra field carries the real sizes/offset when the 32-bit fields are maxed out.
+    let e = p + 46 + nameLen;
+    const end = e + extraLen;
+    while (e + 4 <= end) {
+      const id = buf.readUInt16LE(e);
+      const len = buf.readUInt16LE(e + 2);
+      if (id === 0x0001) {
+        let q = e + 4;
+        if (size === 0xffffffff) { size = Number(buf.readBigUInt64LE(q)); q += 8; }
+        if (compSize === 0xffffffff) { compSize = Number(buf.readBigUInt64LE(q)); q += 8; }
+        if (localOffset === 0xffffffff) { localOffset = Number(buf.readBigUInt64LE(q)); }
+      }
+      e += 4 + len;
+    }
+    entries.push({ name, method, compSize, size, localOffset });
+    p = end + commentLen;
+  }
+  return entries;
+}
+
+function entryData(buf, entry) {
+  const p = entry.localOffset;
+  if (buf.readUInt32LE(p) !== 0x04034b50) throw new Error(`bad local header for ${entry.name}`);
+  const start = p + 30 + buf.readUInt16LE(p + 26) + buf.readUInt16LE(p + 28);
+  const raw = buf.subarray(start, start + entry.compSize);
+  if (entry.method === 0) return raw;
+  if (entry.method === 8) return zlib.inflateRawSync(raw);
+  throw new Error(`unsupported compression ${entry.method} for ${entry.name}`);
+}
+
+// Smallest PT_LOAD alignment of a 64-bit little-endian ELF, or null if it is not one.
+export function minLoadAlignment(elf) {
+  if (elf.length < 64 || elf.readUInt32BE(0) !== 0x7f454c46) return null;
+  if (elf[4] !== 2 || elf[5] !== 1) return null; // ELFCLASS64, little-endian
+  const phoff = Number(elf.readBigUInt64LE(32));
+  const phentsize = elf.readUInt16LE(54);
+  const phnum = elf.readUInt16LE(56);
+  let min = null;
+  for (let i = 0; i < phnum; i++) {
+    const h = phoff + i * phentsize;
+    if (h + 56 > elf.length) break;
+    if (elf.readUInt32LE(h) !== 1) continue; // PT_LOAD
+    const align = Number(elf.readBigUInt64LE(h + 48));
+    if (min === null || align < min) min = align;
+  }
+  return min;
+}
+
+// Returns { file, libs: [{ path, align }], misaligned: [...] } for one APK/AAB.
+export function checkArchive(file) {
+  const buf = fs.readFileSync(file);
+  const libs = [];
+  for (const entry of readZipEntries(buf)) {
+    const m = entry.name.match(/(?:^|\/)lib\/([^/]+)\/[^/]+\.so$/);
+    if (!m || !ABIS_64.includes(m[1])) continue;
+    let align = null;
+    try {
+      align = minLoadAlignment(entryData(buf, entry));
+    } catch {
+      align = null;
+    }
+    if (align !== null) libs.push({ path: entry.name, align });
+  }
+  return { file, libs, misaligned: libs.filter((l) => l.align < PAGE_16K) };
+}
+
+// Most recently built release (preferred) or debug artifact under android/app/build/outputs.
+export function findBuiltArtifact(root) {
+  const base = path.join(root, 'android', 'app', 'build', 'outputs');
+  const found = [];
+  const walk = (dir, depth) => {
+    if (depth > 4) return;
+    let list;
+    try {
+      list = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of list) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) walk(full, depth + 1);
+      else if (/\.(apk|aab)$/.test(e.name)) found.push({ file: full, mtime: fs.statSync(full).mtimeMs, release: /release/i.test(full) });
+    }
+  };
+  walk(base, 0);
+  found.sort((a, b) => Number(b.release) - Number(a.release) || b.mtime - a.mtime);
+  return found[0] ? found[0].file : null;
+}

package/src/interop.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { findPackageDir } from './project.js';
+
+// Static checks for native modules that will run through the New Architecture interop layer
+// (packages without their own codegen spec). Verified on a real upgrade: Kotlin @ReactMethods
+// written as `fun x(...) = scope.launch { }` return a kotlinx.coroutines.Job, the interop only
+// accepts void, and the whole module fails to load (a red screen if it is imported at startup).
+
+const REACT_METHOD_RETURNS_JOB =
+  /@ReactMethod(?!\s*\(\s*isBlockingSynchronousMethod\s*=\s*true)[^\n]*\n(?:\s*@[^\n]*\n)*\s*(?:override\s+)?fun\s+(\w+)\s*\([^)]*\)\s*=\s*(?:[\w.]+\.)?(?:launch|async)\s*[({]/g;
+
+function kotlinFiles(dir, out = []) {
+  let list;
+  try {
+    list = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return out;
+  }
+  for (const e of list) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory()) {
+      if (e.name !== 'build' && e.name !== 'generated') kotlinFiles(full, out);
+    } else if (e.name.endsWith('.kt')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// Returns [{ name, methods: [...] }] for installed native packages with interop-breaking methods.
+export function interopProblems(project, deps) {
+  if (!project.hasNodeModules) return [];
+  const out = [];
+  for (const dep of deps.filter((d) => d.native)) {
+    const dir = findPackageDir(project.root, dep.name);
+    if (!dir) continue;
+    let manifest = {};
+    try {
+      manifest = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    } catch {
+      // unreadable
+    }
+    if (manifest.codegenConfig) continue; // has its own TurboModule spec, no interop involved
+    const methods = [];
+    for (const file of kotlinFiles(path.join(dir, 'android'))) {
+      const text = fs.readFileSync(file, 'utf8');
+      for (const m of text.matchAll(REACT_METHOD_RETURNS_JOB)) methods.push(m[1]);
+    }
+    if (methods.length) out.push({ name: dep.name, version: dep.version, methods });
+  }
+  return out;
+}

package/src/known-issues.js

@@ -0,0 +1,61 @@
+// Version-specific breakages that registries do not know about. Each entry was hit in a real
+// upgrade and records where. This list is the part of NativeKeel that grows with every job.
+//
+// Matching: the installed version of `pkg` is within [from, to] (inclusive, either optional),
+// React Native's minor is within [rnFrom, rnTo], and `when` holds:
+//   'always'      always
+//   'newArch'     the New Architecture is on, or the report says it must be turned on
+
+export const KNOWN_ISSUES = [
+  {
+    id: 'drawer6-reanimated4',
+    pkg: '@react-navigation/drawer',
+    from: '6.0.0',
+    to: '6.99.99',
+    rnFrom: 79,
+    when: 'always',
+    severity: 'medium',
+    title: '@react-navigation/drawer 6 cannot run on Reanimated 4, which React Native 0.82+ needs',
+    detail: "Its drawer uses useAnimatedGestureHandler, removed in Reanimated 4 (found in lib/module/views/modern/Drawer.js). Reanimated 3 supports React Native up to 0.81, so the hop past 0.81 also means React Navigation 7 for every navigator. Plan that JS migration before the React Native hop.",
+    source: 'real upgrade of an RN 0.77 app, 2026-10-03 (source inspection)',
+  },
+  {
+    id: 'rnfs-fork-codegen-eventemitter',
+    pkg: '@dr.pogodin/react-native-fs',
+    from: '2.37.0',
+    rnTo: 77,
+    when: 'always',
+    severity: 'high',
+    title: '@dr.pogodin/react-native-fs 2.37+ breaks pod install on React Native 0.77',
+    detail: "Its TurboModule spec uses EventEmitter properties that this React Native version's codegen rejects (UnsupportedModulePropertyParserError, property 'onDownloadBegin'). Pin 2.36.2 until React Native is upgraded. Its peer range says react-native: *, so npm will not warn you.",
+    source: 'real upgrade of an RN 0.77 app, 2026-10-03',
+  },
+];
+
+// Semver-ish compare on major.minor.patch, ignoring pre-release tags.
+export function compareVersions(a, b) {
+  const pa = String(a).split('-')[0].split('.').map(Number);
+  const pb = String(b).split('-')[0].split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d) return d < 0 ? -1 : 1;
+  }
+  return 0;
+}
+
+export function matchKnownIssues({ deps, rnVersion, newArchOn, newArchRequired }) {
+  const rnMinor = rnVersion ? Number(rnVersion.split('.')[1]) : null;
+  const out = [];
+  for (const issue of KNOWN_ISSUES) {
+    const dep = deps.find((d) => d.name === issue.pkg);
+    if (!dep || !dep.version) continue;
+    if (issue.from && compareVersions(dep.version, issue.from) < 0) continue;
+    if (issue.to && compareVersions(dep.version, issue.to) > 0) continue;
+    if (rnMinor === null) continue;
+    if (issue.rnFrom !== undefined && rnMinor < issue.rnFrom) continue;
+    if (issue.rnTo !== undefined && rnMinor > issue.rnTo) continue;
+    if (issue.when === 'newArch' && !newArchOn && !newArchRequired) continue;
+    out.push({ issue, dep });
+  }
+  return out;
+}