@oxy.so/doctor 1.1.1 → 1.3.0

package/README.md

@@ -15,9 +15,14 @@ bunx @oxy.so/doctor --ci --grace-days=7
 ```
 
 It checks direct dependencies under the canonical `@oxy.so/*` scope against
-npm, reports duplicate
-versions in `bun.lock`, and fails
-clearly when the lockfile is missing.
+npm, reports duplicate versions in `bun.lock`, and fails clearly when the
+lockfile is missing.
+
+It reads the manifests Bun installs from: the root `package.json` and the
+workspaces its `workspaces` patterns match. A `catalog:` dependency is checked
+where its range lives, the root's `workspaces.catalog` (or `catalogs.<name>`).
+A `package.json` outside the workspaces, such as a frozen copy kept as audit
+evidence, is not this repository's dependency state and is not read.
 
 A range that doesn't include the newest published `@oxy.so/*` release is a
 **warning** for 14 days after that release was published (`--grace-days=N`
@@ -27,6 +32,16 @@ gated on it, red at once; each app still has to upgrade inside the window.
 Duplicate locked versions and a missing lockfile are always errors.
 Operational failures use status 2. Default mode is informational.
 
+It also checks that every app (a manifest on `@oxy.so/services` and on `expo`
+or `react-native`) declares each REQUIRED native peer of the services it has
+installed, an **error** otherwise (`undeclared-native-peer`, with the
+`npx expo install …` line). Expo's autolinking skips optional peers and an
+undeclared native module installs at whatever version the package manager
+picks: an Android release without `expo-crypto` built, then had no CSPRNG and
+no sign-in. The check reads the installed `@oxy.so/services` manifest, so run it
+after `bun install`; a manifest whose services is not installed is listed as
+unverified (`nativePeersUnverified` in `--json`), never passed.
+
 Use Renovate with a shared organisation preset for grouped, reviewable updates.
 Require normal tests and typecheck before merging; never use `latest` ranges or
 mutate dependencies during application startup or CI. Renovate proposes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxy.so/doctor",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Read-only health checks for Oxy ecosystem repositories",
   "repository": {
     "type": "git",
@@ -19,8 +19,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "bun test tests",
-    "prepublishOnly": "bun run test"
+    "test": "bun test tests"
   },
   "publishConfig": {
     "access": "public"

package/src/checks.mjs

@@ -1,5 +1,5 @@
 import { readFile, readdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 
 export const FIRST_PARTY_SCOPES = ['@oxy.so/'];
@@ -74,18 +74,155 @@ export async function findRepositoryRoot(start = process.cwd()) {
   }
 }
 
-async function collectManifests(directory, depth = 0) {
-  if (depth > 4) return [];
-  const ignored = new Set(['.git', '.expo', '.turbo', '.worktrees', 'dist', 'lib', 'node_modules']);
-  const entries = await readdir(directory, { withFileTypes: true });
-  const manifests = [];
-  for (const entry of entries) {
-    if (entry.isFile() && entry.name === 'package.json')
-      manifests.push(join(directory, entry.name));
-    if (entry.isDirectory() && !ignored.has(entry.name))
-      manifests.push(...(await collectManifests(join(directory, entry.name), depth + 1)));
+const IGNORED_DIRECTORIES = new Set([
+  '.git',
+  '.expo',
+  '.turbo',
+  '.worktrees',
+  'dist',
+  'lib',
+  'node_modules',
+]);
+
+async function childDirectories(directory) {
+  const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+  return entries
+    .filter((entry) => entry.isDirectory() && !IGNORED_DIRECTORIES.has(entry.name))
+    .map((entry) => join(directory, entry.name));
+}
+
+/** Directories matching one Bun workspace pattern (`dir`, `dir/*`, `dir/**`). */
+async function expandWorkspacePattern(directory, segments) {
+  if (segments.length === 0) return [directory];
+  const [segment, ...rest] = segments;
+  if (segment === '**') {
+    const here = await expandWorkspacePattern(directory, rest);
+    const deeper = await Promise.all(
+      (await childDirectories(directory)).map((child) => expandWorkspacePattern(child, segments)),
+    );
+    return [...here, ...deeper.flat()];
+  }
+  if (segment.includes('*')) {
+    const matcher = new RegExp(
+      `^${segment.replace(/[.+?^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*')}$`,
+    );
+    const children = (await childDirectories(directory)).filter((child) =>
+      matcher.test(child.slice(directory.length + 1)),
+    );
+    return (await Promise.all(children.map((child) => expandWorkspacePattern(child, rest)))).flat();
   }
-  return manifests;
+  return expandWorkspacePattern(join(directory, segment), rest);
+}
+
+/**
+ * The manifests Bun installs from: the root and its workspaces. A package.json
+ * outside them (a frozen copy kept as audit evidence, a fixture) is not
+ * installed from this lockfile, so it is not this repository's dependency state.
+ */
+async function collectManifests(root, rootManifest) {
+  const workspaces = rootManifest.workspaces;
+  const patterns = Array.isArray(workspaces) ? workspaces : (workspaces?.packages ?? []);
+  const directories = new Set([root]);
+  const excluded = new Set();
+  for (const pattern of patterns) {
+    const negated = pattern.startsWith('!');
+    const segments = (negated ? pattern.slice(1) : pattern)
+      .replace(/^\.\//, '')
+      .split('/')
+      .filter(Boolean);
+    for (const directory of await expandWorkspacePattern(root, segments))
+      (negated ? excluded : directories).add(directory);
+  }
+  return [...directories]
+    .filter((directory) => !excluded.has(directory))
+    .map((directory) => join(directory, 'package.json'))
+    .filter((path) => existsSync(path))
+    .sort();
+}
+
+/** `catalog:` / `catalog:<name>` resolved against the root manifest's catalogs. */
+function catalogEntries(rootManifest) {
+  const workspaces = Array.isArray(rootManifest.workspaces) ? {} : (rootManifest.workspaces ?? {});
+  const rows = [];
+  const add = (section, catalog) => {
+    for (const [name, range] of Object.entries(catalog ?? {})) rows.push({ section, name, range });
+  };
+  add('catalog', workspaces.catalog ?? rootManifest.catalog);
+  for (const [catalogName, catalog] of Object.entries(
+    workspaces.catalogs ?? rootManifest.catalogs ?? {},
+  ))
+    add(`catalogs.${catalogName}`, catalog);
+  return rows;
+}
+
+/** The SDK whose native peers an app has to declare itself. */
+export const NATIVE_PEER_HOST = '@oxy.so/services';
+
+/** The installed directory of `name`, found the way Node and Metro walk node_modules. */
+function installedPackageDir(name, from) {
+  let directory = from;
+  while (true) {
+    const candidate = join(directory, 'node_modules', name);
+    if (existsSync(join(candidate, 'package.json'))) return candidate;
+    const parent = dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+/** Ships native code autolinking must link: the markers Expo and the React Native CLI read. */
+export function isNativeModulePackage(directory) {
+  return (
+    existsSync(join(directory, 'expo-module.config.json')) ||
+    existsSync(join(directory, 'react-native.config.js')) ||
+    existsSync(join(directory, 'android')) ||
+    existsSync(join(directory, 'ios')) ||
+    readdirSync(directory).some((entry) => entry.endsWith('.podspec'))
+  );
+}
+
+/**
+ * Required native peers of `@oxy.so/services` that an app (a manifest on
+ * services and on `expo` or `react-native`) does not declare. Expo's autolinking skips OPTIONAL peers, and an undeclared native
+ * module is installed at whatever version the package manager picks rather than
+ * the build `expo install` pins for the app's SDK; `expo-crypto` missing from
+ * Allo's release APK broke the CSPRNG and sign-in. Reads the INSTALLED services
+ * manifest, so it needs `bun install` first; without one the manifest is
+ * reported as unverified rather than passed.
+ *
+ * @returns {Promise<{ finding?: object, unverified?: string }>}
+ */
+export async function nativePeerCheck(root, manifestPath, manifest) {
+  const declared = { ...manifest.dependencies, ...manifest.devDependencies };
+  // Only an APP is autolinked: a manifest on services that is no Expo / React
+  // Native project (a monorepo root holding it for hoisting, a library) is not.
+  if (!(NATIVE_PEER_HOST in declared) || !('expo' in declared || 'react-native' in declared))
+    return {};
+  const relative = manifestPath.slice(root.length + 1);
+  const servicesDir = installedPackageDir(NATIVE_PEER_HOST, dirname(manifestPath));
+  if (!servicesDir) return { unverified: relative };
+  const services = JSON.parse(await readFile(join(servicesDir, 'package.json'), 'utf8'));
+  const meta = services.peerDependenciesMeta ?? {};
+  const missing = Object.keys(services.peerDependencies ?? {})
+    .filter((name) => meta[name]?.optional !== true && !(name in declared))
+    .filter((name) => {
+      const directory = installedPackageDir(name, servicesDir);
+      // Not installed at all: a required peer is missing outright.
+      return directory === null || isNativeModulePackage(directory);
+    })
+    .sort();
+  if (missing.length === 0) return {};
+  return {
+    finding: {
+      severity: 'error',
+      code: 'undeclared-native-peer',
+      package: NATIVE_PEER_HOST,
+      version: services.version,
+      manifest: relative,
+      missing,
+      message: `${relative} uses ${NATIVE_PEER_HOST} ${services.version} but does not declare its required native peer${missing.length === 1 ? '' : 's'} ${missing.join(', ')}; run \`npx expo install ${missing.join(' ')}\` in ${dirname(relative) || '.'}`,
+    },
+  };
 }
 
 /**
@@ -98,8 +235,16 @@ export async function inspectRepository(
   fetchLatest,
   { graceDays = DEFAULT_GRACE_DAYS, now = new Date() } = {},
 ) {
-  const manifestPaths = await collectManifests(root);
+  const rootManifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  const manifestPaths = await collectManifests(root, rootManifest);
   const usages = new Map();
+  const findings = [];
+  for (const { section, name, range } of catalogEntries(rootManifest)) {
+    if (!isFirstPartyPackage(name)) continue;
+    const rows = usages.get(name) ?? [];
+    rows.push({ manifest: 'package.json', section, range });
+    usages.set(name, rows);
+  }
   for (const path of manifestPaths) {
     const manifest = JSON.parse(await readFile(path, 'utf8'));
     for (const section of [
@@ -109,16 +254,27 @@ export async function inspectRepository(
       'optionalDependencies',
     ]) {
       for (const [name, range] of Object.entries(manifest[section] ?? {})) {
-        if (!isFirstPartyPackage(name) || range === 'workspace:*' || range === 'catalog:') continue;
+        if (
+          !isFirstPartyPackage(name) ||
+          range.startsWith('workspace:') ||
+          range.startsWith('catalog:')
+        )
+          continue;
         const rows = usages.get(name) ?? [];
         rows.push({ manifest: path.slice(root.length + 1), section, range });
         usages.set(name, rows);
       }
     }
   }
+  const unverified = [];
+  for (const path of manifestPaths) {
+    const manifest = JSON.parse(await readFile(path, 'utf8'));
+    const result = await nativePeerCheck(root, path, manifest);
+    if (result.finding) findings.push(result.finding);
+    if (result.unverified) unverified.push(result.unverified);
+  }
   const lockPath = join(root, 'bun.lock');
   const lockfile = existsSync(lockPath) ? await readFile(lockPath, 'utf8') : null;
-  const findings = [];
   if (!lockfile)
     findings.push({ severity: 'error', code: 'missing-lockfile', message: 'bun.lock is missing' });
   await Promise.all(
@@ -165,7 +321,13 @@ export async function inspectRepository(
       }
     }),
   );
-  return { root, manifests: manifestPaths.length, packages: usages.size, findings };
+  return {
+    root,
+    manifests: manifestPaths.length,
+    packages: usages.size,
+    findings,
+    nativePeersUnverified: unverified,
+  };
 }
 
 /** The `latest` dist-tag of `name` and when that version was published. */

package/src/cli.mjs

@@ -31,6 +31,10 @@ try {
       `Oxy Doctor: ${report.packages} first-party packages across ${report.manifests} manifests`,
     );
     if (report.findings.length === 0) console.log('✓ No dependency-health findings');
+    for (const manifest of report.nativePeersUnverified)
+      console.log(
+        `? ${manifest}: @oxy.so/services is not installed, so its native peers were not checked (run bun install first)`,
+      );
     for (const finding of report.findings)
       console.log(`${finding.severity === 'error' ? '✗' : '!'} ${finding.message}`);
   }