@reekon-tools/react-native-pdf-canvas 0.1.0

package/scripts/check-skia-peer.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * `bin: pdf-canvas-check-skia` — the install-time gate.
+ *
+ * Thin on purpose: every branch worth testing lives in `skia-peer-check.mjs`,
+ * which does no I/O and never exits. This file is the only place a process exit
+ * code is chosen.
+ *
+ * HOW A CONSUMER WIRES IT UP, and why there are two ways:
+ *
+ *   registry / tarball dependency
+ *     `bin` is linked into `node_modules/.bin`, so the consumer's postinstall
+ *     can just say `pdf-canvas-check-skia`.
+ *
+ *   yarn 1 `link:` dependency (how BOLDR consumes this package)
+ *     MEASURED: a `link:` dependency gets NO `.bin` entries at all, and none of
+ *     its own lifecycle scripts run. The bin name does not exist. Invoke the
+ *     file by path instead — Node follows the symlink (and the Windows junction)
+ *     even though Metro will not:
+ *
+ *       node node_modules/@reekon-tools/react-native-pdf-canvas/scripts/check-skia-peer.mjs
+ *
+ *     That path form works for BOTH kinds of consumer, which is why it is what
+ *     BOLDR's own `postinstall` uses.
+ *
+ * `--strict` promotes every 'unknown'/'prerelease-below' warning to a failure.
+ * Off by default because an unresolvable peer is more often this check standing
+ * in the wrong directory than a genuinely broken app, and a false `yarn install`
+ * failure costs the whole team. CI that owns its own layout can turn it on.
+ *
+ * The outer try/catch is not defensive decoration. An unhandled throw here is a
+ * non-zero exit, i.e. a broken install for a reason that has nothing to do with
+ * skia's version.
+ */
+
+import process from 'node:process';
+
+import {
+  PEER_NAME,
+  evaluate,
+  loadSemver,
+  readOwnFloor,
+  report,
+  resolveConsumerSkia,
+} from './skia-peer-check.mjs';
+
+const strict = process.argv.includes('--strict');
+
+function main() {
+  const {raw: floorRange, name} = readOwnFloor();
+  const selfName = name ?? '@reekon-tools/react-native-pdf-canvas';
+  const found = resolveConsumerSkia();
+
+  const verdict =
+    found.version === null
+      ? {status: 'unknown', message: found.reason, floor: floorRange}
+      : evaluate({
+          found: found.version,
+          floorRange,
+          semver: loadSemver(),
+        });
+
+  const {code, lines} = report(verdict, {selfName, floorRange});
+  for (const line of lines) {
+    (code === 0 ? console.warn : console.error)(line);
+  }
+
+  if (code !== 0) return code;
+  if (strict && verdict.status !== 'ok') {
+    console.error(`  --strict: refusing to pass on "${verdict.status}".`);
+    return 1;
+  }
+  return 0;
+}
+
+let code = 0;
+try {
+  code = main();
+} catch (error) {
+  console.warn(
+    `  [pdf-canvas] could not check the ${PEER_NAME} peer floor: ` +
+      `${error && error.message ? error.message : error}`,
+  );
+  code = strict ? 1 : 0;
+}
+process.exit(code);

package/scripts/skia-peer-check.mjs

@@ -0,0 +1,363 @@
+/**
+ * The skia peer-floor check — pure half.
+ *
+ * Plain `.mjs`, deliberately: this runs from a CONSUMER'S `postinstall`, at
+ * which point `dist/` may not exist. Under yarn 1's `link:` protocol the linked
+ * package's own lifecycle scripts never run at all (measured — see README,
+ * "Enforcing the floor"), so `prepare` has NOT built anything and anything
+ * importing from `dist/` would fail as a missing module. `scripts/` is shipped
+ * verbatim in `files` and needs no build step.
+ *
+ * ---------------------------------------------------------------------------
+ * THE FLOOR IS WRITTEN ONCE, IN `peerDependencies`.
+ * ---------------------------------------------------------------------------
+ *
+ * This module does not restate `2.8.0`. It reads the range out of the package's
+ * own `peerDependencies["@shopify/react-native-skia"]`, so the gate and the
+ * published contract cannot drift apart — a floor bump is a one-line edit to
+ * package.json. `parseFloor` accepts ONLY a bare `>=x.y.z`, and returns null for
+ * anything else, which downgrades the whole check to a warning rather than
+ * letting a compound range be silently misread as its first clause.
+ *
+ * ---------------------------------------------------------------------------
+ * WHICH COPY OF SKIA GETS CHECKED — the trap this module exists to avoid.
+ * ---------------------------------------------------------------------------
+ *
+ * Resolution must start from the CONSUMER, never from this file. Measured in
+ * the BOLDR tree, where the app pins skia 2.6.2 and this package's own dev tree
+ * pins 2.11.0:
+ *
+ *   createRequire(<package dir>) -> 2.11.0   <- the dev copy. A FALSE PASS.
+ *   createRequire(<consumer cwd>) -> 2.6.2   <- the version the app ships.
+ *
+ * Under `link:` the package directory is a symlink to a sibling checkout that
+ * has its own `node_modules`, so the wrong-direction resolution does not fail —
+ * it succeeds, with the answer the author wants to hear. `resolveConsumerSkia`
+ * therefore tries `INIT_CWD` then `process.cwd()`, and refuses to believe a
+ * resolution that landed inside this package while the consumer is somewhere
+ * else. Node's resolver walks parent directories, so a monorepo hoist above the
+ * consumer root is found for free.
+ *
+ * ---------------------------------------------------------------------------
+ * A CRASH HERE IS A BROKEN `yarn install` FOR THE WHOLE APP.
+ * ---------------------------------------------------------------------------
+ *
+ * So the verdict has three outcomes, not two, and only ONE of them is fatal:
+ *
+ *   'ok'                -> exit 0, silent
+ *   'too-low'           -> exit 1. A release version provably below the floor.
+ *   'prerelease-below'  -> warn, exit 0.
+ *   'unknown'           -> warn, exit 0. Skia absent, unparseable version,
+ *                          unparseable floor, self-resolution, thrown error.
+ *
+ * `prerelease-below` follows reanimated's own precedent verbatim
+ * (`scripts/validate-worklets-version.js`: "Don't perform any checks for
+ * pre-release versions, like nightlies or feature previews. The user knows what
+ * they're doing."). It also defends against a real semver footgun: strict
+ * `satisfies('2.12.0-next.1', '>=2.8.0')` is FALSE, because a prerelease only
+ * satisfies a range that names its own [major,minor,patch] tuple. Failing an
+ * install for being too NEW is exactly the wrong reason to fail, so a
+ * prerelease can only ever warn.
+ */
+
+import {createRequire} from 'node:module';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+
+export const PEER_NAME = '@shopify/react-native-skia';
+
+/** This package's root, i.e. the parent of `scripts/`. */
+export const PACKAGE_ROOT = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+);
+
+/**
+ * A bare `>=x.y.z` and nothing else. Anything more expressive (a caret, an ` || `
+ * union, a prerelease floor) returns null and the check degrades to a warning —
+ * see the header. This is a deliberate refusal to guess.
+ */
+const FLOOR_SHAPE = /^>=\s*(\d+)\.(\d+)\.(\d+)$/;
+
+const VERSION_SHAPE =
+  /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/;
+
+/** @typedef {{range: string, tuple: [number, number, number]}} Floor */
+/** @typedef {{tuple: [number, number, number], prerelease: string | null}} Parsed */
+
+/** @returns {Floor | null} */
+export function parseFloor(range) {
+  if (typeof range !== 'string') return null;
+  const m = FLOOR_SHAPE.exec(range.trim());
+  if (m === null) return null;
+  return {range: range.trim(), tuple: [+m[1], +m[2], +m[3]]};
+}
+
+/** @returns {Parsed | null} */
+export function parseVersion(version) {
+  if (typeof version !== 'string') return null;
+  const m = VERSION_SHAPE.exec(version.trim());
+  if (m === null) return null;
+  return {tuple: [+m[1], +m[2], +m[3]], prerelease: m[4] ?? null};
+}
+
+function compareTuple(a, b) {
+  for (let i = 0; i < 3; i++) {
+    if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * `semver.satisfies(version, '>=x.y.z', {includePrerelease: true})`,
+ * reimplemented in six lines because the package ships no runtime dependencies
+ * and a `link:` consumer would not get one installed even if it did.
+ *
+ * The one non-obvious rule, and the reason this is not a bare tuple compare:
+ * for an EQUAL tuple a prerelease is LOWER, so `2.8.0-next.1` does not meet a
+ * `>=2.8.0` floor while `2.12.0-next.1` does. `peer-check.test.ts` asserts this
+ * function agrees with the real `semver` over a table that includes every
+ * prerelease in skia's published history.
+ *
+ * @param {Parsed} v
+ * @param {Floor} floor
+ */
+export function meetsFloor(v, floor) {
+  const c = compareTuple(v.tuple, floor.tuple);
+  if (c !== 0) return c > 0;
+  return v.prerelease === null;
+}
+
+/**
+ * Use the real `semver` when the tree happens to have one, and fall back
+ * otherwise. Both arms are exercised in the wild — a `link:` consumer resolves
+ * this package's dev copy, a tarball consumer with no semver anywhere gets the
+ * fallback — so `peer-check.test.ts` pins them to the same answers rather than
+ * trusting that they agree.
+ */
+export function loadSemver(requireFrom = createRequire(import.meta.url)) {
+  try {
+    const satisfies = requireFrom('semver/functions/satisfies');
+    return typeof satisfies === 'function' ? {satisfies} : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {Parsed} v
+ * @param {Floor} floor
+ */
+export function meetsFloorVia(semver, rawVersion, v, floor) {
+  if (semver !== null) {
+    try {
+      return semver.satisfies(rawVersion, floor.range, {
+        includePrerelease: true,
+      });
+    } catch {
+      // fall through to the built-in comparison
+    }
+  }
+  return meetsFloor(v, floor);
+}
+
+/**
+ * Roots to resolve the peer from, most authoritative first. `INIT_CWD` is set by
+ * yarn 1 and npm to the directory the install was invoked in; `process.cwd()` is
+ * what a `postinstall` actually runs in (measured: the consumer root, for both a
+ * `link:` and a tarball dependency).
+ */
+export function consumerRoots(env = process.env, cwd = process.cwd()) {
+  const roots = [];
+  for (const candidate of [env['INIT_CWD'], cwd]) {
+    if (typeof candidate !== 'string' || candidate.length === 0) continue;
+    const resolved = path.resolve(candidate);
+    if (!roots.includes(resolved)) roots.push(resolved);
+  }
+  return roots;
+}
+
+const isInside = (child, parent) => {
+  const rel = path.relative(parent, child);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+};
+
+/**
+ * `isInside` OR equal, and the difference is a real bug that the suite caught:
+ * the consumer root can legitimately BE this package's root (`yarn check:peers`
+ * in the dev tree). Treating that as "not our tree" made the false-pass guard
+ * fire on the one case where reading our own copy is exactly right.
+ */
+const isAtOrInside = (child, parent) =>
+  path.resolve(child) === path.resolve(parent) || isInside(child, parent);
+
+/**
+ * Find the consumer's installed peer.
+ *
+ * @returns {{version: string, from: string, dir: string}
+ *   | {version: null, reason: string}}
+ */
+export function resolveConsumerSkia({
+  roots = consumerRoots(),
+  packageRoot = PACKAGE_ROOT,
+  makeRequire = root => createRequire(path.join(root, 'noop.js')),
+} = {}) {
+  const tried = [];
+  for (const root of roots) {
+    let manifestPath;
+    try {
+      manifestPath = makeRequire(root).resolve(`${PEER_NAME}/package.json`);
+    } catch {
+      tried.push(root);
+      continue;
+    }
+    const dir = path.dirname(manifestPath);
+    // The measured false-pass guard: a resolution that landed in our own dev
+    // tree tells us about US, not about the consumer.
+    if (isInside(dir, packageRoot) && !isAtOrInside(root, packageRoot)) {
+      return {
+        version: null,
+        reason:
+          `${PEER_NAME} resolved to ${dir}, which is inside this package's ` +
+          `own dev tree rather than the consumer's (${root}). That copy is ` +
+          'not what the app ships, so no verdict is possible.',
+      };
+    }
+    let version;
+    try {
+      version = makeRequire(root)(`${PEER_NAME}/package.json`).version;
+    } catch (error) {
+      return {
+        version: null,
+        reason: `${PEER_NAME}/package.json at ${dir} could not be read (${
+          error && error.message ? error.message : error
+        }).`,
+      };
+    }
+    if (typeof version !== 'string') {
+      return {
+        version: null,
+        reason: `${PEER_NAME}/package.json at ${dir} has no "version" string.`,
+      };
+    }
+    return {version, from: root, dir};
+  }
+  return {
+    version: null,
+    reason:
+      `${PEER_NAME} is not resolvable from ${
+        tried.length > 0 ? tried.join(' or ') : 'anywhere'
+      }. It is a REQUIRED peer, not an optional one — but "not installed yet" ` +
+      'and "installed somewhere this check cannot see" are indistinguishable ' +
+      'from here, so this is a warning.',
+  };
+}
+
+/** Read our own declared floor. Never throws. */
+export function readOwnFloor(
+  manifestPath = path.join(PACKAGE_ROOT, 'package.json'),
+) {
+  try {
+    const manifest = createRequire(import.meta.url)(manifestPath);
+    const peers = manifest && manifest.peerDependencies;
+    return {
+      raw: peers ? peers[PEER_NAME] : undefined,
+      name: manifest && manifest.name,
+    };
+  } catch (error) {
+    return {raw: undefined, name: undefined, error};
+  }
+}
+
+/**
+ * The whole decision, as data. No I/O, no `process.exit` — that is the CLI's
+ * job, and keeping them apart is what makes every branch below testable.
+ *
+ * @returns {{status: 'ok' | 'too-low' | 'prerelease-below' | 'unknown',
+ *   message: string, found?: string, floor?: string}}
+ */
+export function evaluate({found, floorRange, packageName = PEER_NAME, semver}) {
+  const floor = parseFloor(floorRange);
+  if (floor === null) {
+    return {
+      status: 'unknown',
+      message:
+        `Cannot check ${PEER_NAME}: this package declares the peer range ` +
+        `${JSON.stringify(floorRange)}, and this check only understands a ` +
+        'bare ">=x.y.z". Refusing to guess.',
+    };
+  }
+  if (found === null || found === undefined) {
+    return {status: 'unknown', message: 'No installed version was resolved.'};
+  }
+  const parsed = parseVersion(found);
+  if (parsed === null) {
+    return {
+      status: 'unknown',
+      message:
+        `Cannot check ${PEER_NAME}: the installed version ` +
+        `${JSON.stringify(found)} is not a semver release or prerelease.`,
+      floor: floor.range,
+    };
+  }
+  if (meetsFloorVia(semver ?? null, found, parsed, floor)) {
+    return {
+      status: 'ok',
+      message: `${PEER_NAME} ${found} satisfies ${floor.range}.`,
+      found,
+      floor: floor.range,
+    };
+  }
+  if (parsed.prerelease !== null) {
+    return {
+      status: 'prerelease-below',
+      message:
+        `${PEER_NAME} ${found} is a PRERELEASE below ${floor.range}. Not ` +
+        'failing the install — a prerelease is an explicit opt-in, and ' +
+        'strict semver would also reject a prerelease of a NEWER minor. ' +
+        'Verify it yourself.',
+      found,
+      floor: floor.range,
+    };
+  }
+  return {
+    status: 'too-low',
+    message: `${PEER_NAME} ${found} is below the required ${floor.range}.`,
+    found,
+    floor: floor.range,
+    packageName,
+  };
+}
+
+/**
+ * The exit code and the text the developer actually reads. Actionable means all
+ * three of: what was found, what is required, and the command that fixes it.
+ *
+ * @returns {{code: 0 | 1, lines: string[]}}
+ */
+export function report(verdict, {selfName = PEER_NAME, floorRange} = {}) {
+  const floor = verdict.floor ?? floorRange ?? '';
+  if (verdict.status === 'ok') return {code: 0, lines: []};
+  if (verdict.status === 'too-low') {
+    return {
+      code: 1,
+      lines: [
+        '',
+        `  ${selfName} requires ${PEER_NAME} ${floor}.`,
+        `  Found: ${verdict.found}`,
+        '',
+        `  Below ${floor} the RN Web reconciler leaks one CanvasKit Paint per`,
+        '  drawn tile per frame into the Emscripten heap, which never shrinks.',
+        "  This package's tiling makes that leak proportional to the number of",
+        '  pieces on screen, so its memory policy cannot hold there.',
+        '',
+        `  Fix:  yarn add ${PEER_NAME}@^${floor.replace(/^>=\s*/, '')}`,
+        '',
+      ],
+    };
+  }
+  return {
+    code: 0,
+    lines: ['', `  [${selfName}] ${verdict.message}`, ''],
+  };
+}