@oxy.so/doctor 0.1.1

package/README.md

@@ -0,0 +1,25 @@
+# Oxy Doctor
+
+Read-only health checks for JavaScript/TypeScript repositories in the Oxy
+ecosystem. Doctor never edits manifests, installs packages, or bypasses a
+lockfile; dependency changes remain reviewable commits produced by Renovate or
+a developer.
+
+## Usage
+
+```bash
+bunx @oxy.so/doctor
+bunx @oxy.so/doctor --ci
+bunx @oxy.so/doctor --json
+```
+
+It checks direct dependencies under canonical `@oxy.so/*`, transitional
+`@oxyhq/*`, `@clarity.surf/*`, and `@alia.onl/*` against npm, reports duplicate
+versions in `bun.lock`, and fails
+clearly when the lockfile is missing. `--ci` exits 1 for findings; operational
+failures use status 2. Default mode is informational.
+
+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
+changes; Doctor detects drift and duplicate installations.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@oxy.so/doctor",
+  "version": "0.1.1",
+  "description": "Read-only health checks for Oxy ecosystem repositories",
+  "type": "module",
+  "bin": {
+    "oxy-doctor": "./src/cli.mjs"
+  },
+  "exports": {
+    ".": "./src/checks.mjs"
+  },
+  "files": ["src", "README.md"],
+  "scripts": {
+    "test": "bun test tests",
+    "prepublishOnly": "bun run test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}

package/src/checks.mjs

@@ -0,0 +1,107 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+
+export const FIRST_PARTY_SCOPES = ['@oxy.so/', '@oxyhq/', '@clarity.surf/', '@alia.onl/'];
+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 a = parse(left);
+  const b = parse(right);
+  for (let index = 0; index < 3; index += 1) {
+    if (a[index] !== b[index]) return a[index] < b[index] ? -1 : 1;
+  }
+  return 0;
+}
+
+export function rangeIncludesVersion(range, version) {
+  return range.split('||').some((alternative) => {
+    const terms = alternative.trim().split(/\s+/).filter(Boolean);
+    return terms.every((term) => {
+      const target = term.match(/\d+\.\d+\.\d+/)?.[0];
+      if (!target) return true;
+      const comparison = compareVersions(version, target);
+      if (term.startsWith('>=')) return comparison >= 0;
+      if (term.startsWith('<=')) return comparison <= 0;
+      if (term.startsWith('>')) return comparison > 0;
+      if (term.startsWith('<')) return comparison < 0;
+      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);
+      }
+      if (term.startsWith('~')) {
+        const [major, minor] = target.split('.').map(Number);
+        const [candidateMajor, candidateMinor] = version.split('.').map(Number);
+        return comparison >= 0 && candidateMajor === major && candidateMinor === minor;
+      }
+      return comparison === 0;
+    });
+  });
+}
+
+export function lockfileVersions(lockfile, packageName) {
+  const escaped = packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const matcher = new RegExp(`"(?:[^"\\n]+/)?${escaped}"\\s*:\\s*\\["${escaped}@([^"\\s]+)"`, 'g');
+  return [...lockfile.matchAll(matcher)].map((match) => match[1]);
+}
+
+export async function findRepositoryRoot(start = process.cwd()) {
+  let current = resolve(start);
+  while (true) {
+    if (existsSync(join(current, 'package.json'))) return current;
+    const parent = dirname(current);
+    if (parent === current) throw new Error(`No package.json found above ${start}`);
+    current = parent;
+  }
+}
+
+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));
+  }
+  return manifests;
+}
+
+export async function inspectRepository(root, fetchLatest) {
+  const manifestPaths = await collectManifests(root);
+  const usages = new Map();
+  for (const path of manifestPaths) {
+    const manifest = JSON.parse(await readFile(path, 'utf8'));
+    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;
+        const rows = usages.get(name) ?? [];
+        rows.push({ manifest: path.slice(root.length + 1), section, range });
+        usages.set(name, rows);
+      }
+    }
+  }
+  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 latest = await fetchLatest(name);
+    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)) findings.push({ severity: 'warning', code: 'outdated', package: name, latest, ...row, message: `${name} ${row.range} does not include ${latest} in ${row.manifest}` });
+    }
+  }));
+  return { root, manifests: manifestPaths.length, packages: usages.size, findings };
+}
+
+export async function fetchLatestVersion(name) {
+  const response = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}/latest`, { headers: { accept: 'application/json' } });
+  if (!response.ok) throw new Error(`Registry returned ${response.status} for ${name}`);
+  const metadata = await response.json();
+  if (typeof metadata.version !== 'string') throw new Error(`Registry returned no version for ${name}`);
+  return metadata.version;
+}

package/src/cli.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { fetchLatestVersion, findRepositoryRoot, inspectRepository } from './checks.mjs';
+
+const args = new Set(process.argv.slice(2));
+if (args.has('--help') || args.has('-h')) {
+  console.log('oxy-doctor [--ci] [--json]\n\nRead-only checks for Oxy ecosystem dependency health.');
+  process.exit(0);
+}
+try {
+  const report = await inspectRepository(await findRepositoryRoot(), fetchLatestVersion);
+  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`);
+    if (report.findings.length === 0) console.log('✓ No dependency-health findings');
+    for (const finding of report.findings) console.log(`${finding.severity === 'error' ? '✗' : '!'} ${finding.message}`);
+  }
+  if (args.has('--ci') && report.findings.length > 0) process.exitCode = 1;
+} catch (error) {
+  console.error(`Oxy Doctor failed: ${error instanceof Error ? error.message : String(error)}`);
+  process.exitCode = 2;
+}