@oxy.so/doctor 1.1.0 → 1.2.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`

package/package.json

@@ -1,7 +1,12 @@
 {
   "name": "@oxy.so/doctor",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Read-only health checks for Oxy ecosystem repositories",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OxyHQ/oxy.git",
+    "directory": "packages/doctor"
+  },
   "type": "module",
   "bin": {
     "oxy-doctor": "./src/cli.mjs"
@@ -9,7 +14,10 @@
   "exports": {
     ".": "./src/checks.mjs"
   },
-  "files": ["src", "README.md"],
+  "files": [
+    "src",
+    "README.md"
+  ],
   "scripts": {
     "test": "bun test tests",
     "prepublishOnly": "bun run test"

package/src/checks.mjs

@@ -12,10 +12,16 @@ export const FIRST_PARTY_SCOPES = ['@oxy.so/'];
  */
 export const DEFAULT_GRACE_DAYS = 14;
 const DAY_MS = 24 * 60 * 60 * 1000;
-export const isFirstPartyPackage = (name) => FIRST_PARTY_SCOPES.some((scope) => name.startsWith(scope));
+export const isFirstPartyPackage = (name) =>
+  FIRST_PARTY_SCOPES.some((scope) => name.startsWith(scope));
 
 export function compareVersions(left, right) {
-  const parse = (value) => value.replace(/^v/, '').split(/[.-]/).slice(0, 3).map((part) => Number(part) || 0);
+  const parse = (value) =>
+    value
+      .replace(/^v/, '')
+      .split(/[.-]/)
+      .slice(0, 3)
+      .map((part) => Number(part) || 0);
   const a = parse(left);
   const b = parse(right);
   for (let index = 0; index < 3; index += 1) {
@@ -38,7 +44,9 @@ export function rangeIncludesVersion(range, version) {
       if (term.startsWith('^')) {
         const [major, minor] = target.split('.').map(Number);
         const [candidateMajor, candidateMinor] = version.split('.').map(Number);
-        return comparison >= 0 && candidateMajor === major && (major > 0 || candidateMinor === minor);
+        return (
+          comparison >= 0 && candidateMajor === major && (major > 0 || candidateMinor === minor)
+        );
       }
       if (term.startsWith('~')) {
         const [major, minor] = target.split('.').map(Number);
@@ -66,16 +74,85 @@ 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;
 }
 
 /**
@@ -83,14 +160,35 @@ async function collectManifests(directory, depth = 0) {
  * @param {(name: string) => Promise<{ version: string, publishedAt: string }>} fetchLatest
  * @param {{ graceDays?: number, now?: Date }} [options]
  */
-export async function inspectRepository(root, fetchLatest, { graceDays = DEFAULT_GRACE_DAYS, now = new Date() } = {}) {
-  const manifestPaths = await collectManifests(root);
+export async function inspectRepository(
+  root,
+  fetchLatest,
+  { graceDays = DEFAULT_GRACE_DAYS, now = new Date() } = {},
+) {
+  const rootManifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  const manifestPaths = await collectManifests(root, rootManifest);
   const usages = new Map();
+  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 ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+    for (const section of [
+      'dependencies',
+      'devDependencies',
+      'peerDependencies',
+      '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);
@@ -100,34 +198,67 @@ export async function inspectRepository(root, fetchLatest, { graceDays = DEFAULT
   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([...usages].map(async ([name, rows]) => {
-    const { version: latest, publishedAt } = await fetchLatest(name);
-    const published = new Date(publishedAt);
-    if (Number.isNaN(published.getTime())) throw new Error(`Registry returned no publish time for ${name}@${latest}`);
-    const deadline = new Date(published.getTime() + graceDays * DAY_MS);
-    const overdue = now >= deadline;
-    const installed = lockfile ? [...new Set(lockfileVersions(lockfile, name))] : [];
-    if (installed.length > 1) findings.push({ severity: 'error', code: 'duplicate-version', package: name, installed, message: `${name} has multiple locked versions: ${installed.join(', ')}` });
-    for (const row of rows) {
-      if (rangeIncludesVersion(row.range, latest)) continue;
-      const due = deadline.toISOString().slice(0, 10);
-      findings.push(overdue
-        ? { severity: 'error', code: 'outdated', package: name, latest, publishedAt, ...row, message: `${name} ${row.range} does not include ${latest} in ${row.manifest} (published ${publishedAt.slice(0, 10)}; the ${graceDays}-day upgrade window closed ${due})` }
-        : { severity: 'warning', code: 'outdated', package: name, latest, publishedAt, ...row, message: `${name} ${row.range} does not include ${latest} in ${row.manifest} (upgrade by ${due})` });
-    }
-  }));
+  if (!lockfile)
+    findings.push({ severity: 'error', code: 'missing-lockfile', message: 'bun.lock is missing' });
+  await Promise.all(
+    [...usages].map(async ([name, rows]) => {
+      const { version: latest, publishedAt } = await fetchLatest(name);
+      const published = new Date(publishedAt);
+      if (Number.isNaN(published.getTime()))
+        throw new Error(`Registry returned no publish time for ${name}@${latest}`);
+      const deadline = new Date(published.getTime() + graceDays * DAY_MS);
+      const overdue = now >= deadline;
+      const installed = lockfile ? [...new Set(lockfileVersions(lockfile, name))] : [];
+      if (installed.length > 1)
+        findings.push({
+          severity: 'error',
+          code: 'duplicate-version',
+          package: name,
+          installed,
+          message: `${name} has multiple locked versions: ${installed.join(', ')}`,
+        });
+      for (const row of rows) {
+        if (rangeIncludesVersion(row.range, latest)) continue;
+        const due = deadline.toISOString().slice(0, 10);
+        findings.push(
+          overdue
+            ? {
+                severity: 'error',
+                code: 'outdated',
+                package: name,
+                latest,
+                publishedAt,
+                ...row,
+                message: `${name} ${row.range} does not include ${latest} in ${row.manifest} (published ${publishedAt.slice(0, 10)}; the ${graceDays}-day upgrade window closed ${due})`,
+              }
+            : {
+                severity: 'warning',
+                code: 'outdated',
+                package: name,
+                latest,
+                publishedAt,
+                ...row,
+                message: `${name} ${row.range} does not include ${latest} in ${row.manifest} (upgrade by ${due})`,
+              },
+        );
+      }
+    }),
+  );
   return { root, manifests: manifestPaths.length, packages: usages.size, findings };
 }
 
 /** The `latest` dist-tag of `name` and when that version was published. */
 export async function fetchLatestRelease(name) {
-  const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}`, { headers: { accept: 'application/json' } });
+  const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}`, {
+    headers: { accept: 'application/json' },
+  });
   if (!response.ok) throw new Error(`Registry returned ${response.status} for ${name}`);
   const metadata = await response.json();
   const version = metadata['dist-tags']?.latest;
-  if (typeof version !== 'string') throw new Error(`Registry returned no latest version for ${name}`);
+  if (typeof version !== 'string')
+    throw new Error(`Registry returned no latest version for ${name}`);
   const publishedAt = metadata.time?.[version];
-  if (typeof publishedAt !== 'string') throw new Error(`Registry returned no publish time for ${name}@${version}`);
+  if (typeof publishedAt !== 'string')
+    throw new Error(`Registry returned no publish time for ${name}@${version}`);
   return { version, publishedAt };
 }

package/src/cli.mjs

@@ -1,27 +1,41 @@
 #!/usr/bin/env node
-import { DEFAULT_GRACE_DAYS, fetchLatestRelease, findRepositoryRoot, inspectRepository } from './checks.mjs';
+import {
+  DEFAULT_GRACE_DAYS,
+  fetchLatestRelease,
+  findRepositoryRoot,
+  inspectRepository,
+} from './checks.mjs';
 
 const argv = process.argv.slice(2);
 const args = new Set(argv);
 if (args.has('--help') || args.has('-h')) {
-  console.log(`oxy-doctor [--ci] [--json] [--grace-days=N]\n\nRead-only checks for Oxy ecosystem dependency health.\nA newer @oxy.so release is a warning for N days after it is published (default ${DEFAULT_GRACE_DAYS}), then an error.\n--ci exits 1 on errors only.`);
+  console.log(
+    `oxy-doctor [--ci] [--json] [--grace-days=N]\n\nRead-only checks for Oxy ecosystem dependency health.\nA newer @oxy.so release is a warning for N days after it is published (default ${DEFAULT_GRACE_DAYS}), then an error.\n--ci exits 1 on errors only.`,
+  );
   process.exit(0);
 }
 const graceArg = argv.find((value) => value.startsWith('--grace-days='));
-const graceDays = graceArg === undefined ? DEFAULT_GRACE_DAYS : Number(graceArg.slice('--grace-days='.length));
+const graceDays =
+  graceArg === undefined ? DEFAULT_GRACE_DAYS : Number(graceArg.slice('--grace-days='.length));
 if (!Number.isInteger(graceDays) || graceDays < 0) {
   console.error('Oxy Doctor failed: --grace-days must be a non-negative integer');
   process.exit(2);
 }
 try {
-  const report = await inspectRepository(await findRepositoryRoot(), fetchLatestRelease, { graceDays });
+  const report = await inspectRepository(await findRepositoryRoot(), fetchLatestRelease, {
+    graceDays,
+  });
   if (args.has('--json')) console.log(JSON.stringify(report, null, 2));
   else {
-    console.log(`Oxy Doctor: ${report.packages} first-party packages across ${report.manifests} manifests`);
+    console.log(
+      `Oxy Doctor: ${report.packages} first-party packages across ${report.manifests} manifests`,
+    );
     if (report.findings.length === 0) console.log('✓ No dependency-health findings');
-    for (const finding of report.findings) console.log(`${finding.severity === 'error' ? '✗' : '!'} ${finding.message}`);
+    for (const finding of report.findings)
+      console.log(`${finding.severity === 'error' ? '✗' : '!'} ${finding.message}`);
   }
-  if (args.has('--ci') && report.findings.some((finding) => finding.severity === 'error')) process.exitCode = 1;
+  if (args.has('--ci') && report.findings.some((finding) => finding.severity === 'error'))
+    process.exitCode = 1;
 } catch (error) {
   console.error(`Oxy Doctor failed: ${error instanceof Error ? error.message : String(error)}`);
   process.exitCode = 2;