jeo-code 0.12.20 → 0.12.22

package/src/util/shared-global.ts

@@ -0,0 +1,380 @@
+/**
+ * Read-only view of the shared bun global install (`~/.bun/install/global`) that `jeo update`
+ * writes into with `bun install -g jeo-code@V`. That directory also holds other tools (jeopi,
+ * gajae-code, ...), so `jeo update` must prove it leaves every other top-level package alone.
+ *
+ * This module only ever reads: it never writes, deletes, renames, spawns or executes anything.
+ * Restore commands are formatted as strings for a human to run.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { currentJeoCommand } from "../messenger/launcher";
+
+export const SELF_PACKAGE = "jeo-code";
+
+export type EnvLike = Readonly<Record<string, string | undefined>>;
+export type GlobalSkipReason = "windows" | "no-home" | "no-bun-global" | "manifest-unreadable" | "bunfig-global-dir";
+export type LocatedGlobal = { ok: true; dir: string } | { ok: false; reason: GlobalSkipReason; detail?: string };
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function errorMessage(err: unknown): string {
+  if (err !== null && typeof err === "object" && "message" in err && typeof err.message === "string") return err.message;
+  return String(err);
+}
+
+function errorCode(err: unknown): string | undefined {
+  if (err !== null && typeof err === "object" && "code" in err && typeof err.code === "string") return err.code;
+  return undefined;
+}
+
+type ParsedFile = { ok: true; value: Record<string, unknown> } | { ok: false; missing: boolean; error: string };
+
+/** Reads and JSONC-parses a file that must hold an object. `missing` is true only for ENOENT/ENOTDIR. */
+function parseJsonObject(file: string): ParsedFile {
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch (err) {
+    const code = errorCode(err);
+    return { ok: false, missing: code === "ENOENT" || code === "ENOTDIR", error: errorMessage(err) };
+  }
+  let doc: unknown;
+  try {
+    doc = Bun.JSONC.parse(text);
+  } catch (err) {
+    return { ok: false, missing: false, error: errorMessage(err) };
+  }
+  if (!isRecord(doc)) return { ok: false, missing: false, error: "not a JSON object" };
+  return { ok: true, value: doc };
+}
+
+/**
+ * Where bun keeps its global install: `$BUN_INSTALL_GLOBAL_DIR`, else `${BUN_INSTALL:-$HOME/.bun}/install/global`.
+ * Null when neither an override nor a home directory is available, or on Windows (never inspected there).
+ */
+export function candidateGlobalDir(env: EnvLike, home: string | undefined, platform: NodeJS.Platform): string | null {
+  if (platform === "win32") return null;
+  const override = env.BUN_INSTALL_GLOBAL_DIR;
+  if (override) return path.resolve(override);
+  const installRoot = env.BUN_INSTALL || (home ? path.join(home, ".bun") : undefined);
+  return installRoot ? path.join(installRoot, "install", "global") : null;
+}
+
+const BUNFIG_GLOBAL_DIR_KEY = /^\s*(?:install\s*\.\s*)?["']?globalDir["']?\s*=/;
+
+/** The bunfig.toml that sets a `globalDir`, if any (a user-level one moves the global dir independently of the env). */
+function bunfigWithGlobalDir(env: EnvLike, home: string | undefined): string | null {
+  const files: string[] = [];
+  if (home) files.push(path.join(home, ".bunfig.toml"));
+  if (env.XDG_CONFIG_HOME) files.push(path.join(env.XDG_CONFIG_HOME, ".bunfig.toml"));
+  for (const file of files) {
+    let text: string;
+    try {
+      text = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    if (text.split(/\r?\n/).some(line => BUNFIG_GLOBAL_DIR_KEY.test(line))) return file;
+  }
+  return null;
+}
+
+/**
+ * Resolves the shared bun global dir and proves it holds a parseable package.json. A compiled jeo is NOT a
+ * skip reason: `jeo update` runs `bun install -g` into this same directory from a compiled binary too.
+ * `entry` and `execPath` are accepted so one options object serves both this and detectInstallOrigin.
+ */
+export function locateSharedGlobal(o: { env?: EnvLike; home?: string; platform?: NodeJS.Platform; entry?: string; execPath?: string } = {}): LocatedGlobal {
+  const env = o.env ?? process.env;
+  const platform = o.platform ?? process.platform;
+  if (platform === "win32") return { ok: false, reason: "windows" };
+  const home = o.home ?? (env.HOME || undefined);
+  const bunfig = bunfigWithGlobalDir(env, home);
+  if (bunfig) return { ok: false, reason: "bunfig-global-dir", detail: bunfig };
+  const candidate = candidateGlobalDir(env, home, platform);
+  if (!candidate) return { ok: false, reason: "no-home" };
+  const manifest = parseJsonObject(path.join(candidate, "package.json"));
+  if (!manifest.ok) {
+    return manifest.missing
+      ? { ok: false, reason: "no-bun-global", detail: candidate }
+      : { ok: false, reason: "manifest-unreadable", detail: manifest.error };
+  }
+  let dir = candidate;
+  try {
+    dir = fs.realpathSync(candidate);
+  } catch {
+    // The manifest was just read from the candidate path, so keep it when realpath fails.
+  }
+  return { ok: true, dir };
+}
+
+export interface ManifestDeps {
+  names: string[];
+  specs: Record<string, string>;
+  external: string[];
+  ignored: string[];
+}
+
+/**
+ * Top-level dependencies of the global package.json. Empty names and non-string specs are dropped into
+ * `ignored` (an older jeopi wrote a `"": "."` dependency that no lockfile could ever cover). `external` is
+ * every name except jeo-code, in manifest order. An absent `dependencies` means zero dependencies.
+ */
+export function readManifestDeps(dir: string): { ok: true; deps: ManifestDeps } | { ok: false; error: string } {
+  const manifest = parseJsonObject(path.join(dir, "package.json"));
+  if (!manifest.ok) return { ok: false, error: manifest.error };
+  const raw = manifest.value.dependencies;
+  if (raw !== undefined && raw !== null && !isRecord(raw)) return { ok: false, error: "dependencies is not an object" };
+  const names: string[] = [];
+  const specs: [string, string][] = [];
+  const ignored: string[] = [];
+  for (const [name, spec] of Object.entries(raw ?? {})) {
+    if (name === "" || typeof spec !== "string") {
+      ignored.push(name);
+      continue;
+    }
+    names.push(name);
+    specs.push([name, spec]);
+  }
+  return { ok: true, deps: { names, specs: Object.fromEntries(specs), external: names.filter(n => n !== SELF_PACKAGE), ignored } };
+}
+
+export type LockStatus = "ok" | "missing" | "incomplete" | "unreadable" | "not-required";
+export interface LockCoverage {
+  status: LockStatus;
+  uncovered: string[];
+  path: string;
+  detail?: string;
+  legacyBinaryLock?: boolean;
+}
+
+/**
+ * Whether `bun.lock` carries a resolved entry for every external dependency. Bun's text lockfile is JSONC;
+ * a direct dependency is an OWN key of `packages` equal to its name (nested copies are `parent/name`, and the
+ * root workspace under `workspaces[""]` merely mirrors the manifest), and its value is a tuple whose first
+ * element is the resolved `name@version` string. lockfileVersion and tuple length are deliberately not gated.
+ */
+export function checkLockCoverage(dir: string, external: readonly string[]): LockCoverage {
+  const lockPath = path.join(dir, "bun.lock");
+  if (external.length === 0) return { status: "not-required", uncovered: [], path: lockPath };
+  let text: string;
+  try {
+    text = fs.readFileSync(lockPath, "utf8");
+  } catch (err) {
+    const missing = errorCode(err) === "ENOENT";
+    return {
+      status: missing ? "missing" : "unreadable",
+      uncovered: [...external],
+      path: lockPath,
+      detail: missing ? undefined : errorMessage(err),
+      legacyBinaryLock: missing && fs.existsSync(path.join(dir, "bun.lockb")),
+    };
+  }
+  let doc: unknown;
+  try {
+    doc = Bun.JSONC.parse(text);
+  } catch (err) {
+    return { status: "unreadable", uncovered: [...external], path: lockPath, detail: errorMessage(err) };
+  }
+  const packages = isRecord(doc) ? doc.packages : undefined;
+  if (!isRecord(packages)) return { status: "unreadable", uncovered: [...external], path: lockPath, detail: "no packages map" };
+  const uncovered = external.filter(name => {
+    if (!Object.hasOwn(packages, name)) return true;
+    const entry = packages[name];
+    return !(Array.isArray(entry) && typeof entry[0] === "string" && entry[0].length > 0);
+  });
+  return { status: uncovered.length > 0 ? "incomplete" : "ok", uncovered, path: lockPath };
+}
+
+export type InstalledSnapshot = Record<string, string | null>;
+
+function installedVersion(dir: string, name: string): string | null {
+  if (name === "" || name === SELF_PACKAGE || name.includes("..") || path.isAbsolute(name)) return null;
+  const manifest = parseJsonObject(path.join(dir, "node_modules", name, "package.json"));
+  if (!manifest.ok) return null;
+  return typeof manifest.value.version === "string" ? manifest.value.version : null;
+}
+
+/**
+ * Installed version of each named package (read from `dir/node_modules/<name>/package.json`), null when it is
+ * absent or unreadable, has no string version, is jeo-code itself, has an unsafe name, or `present` lacks it.
+ */
+export function snapshotInstalled(dir: string, names: readonly string[], present?: ReadonlySet<string>): InstalledSnapshot {
+  return Object.fromEntries(names.map(name => [name, present && !present.has(name) ? null : installedVersion(dir, name)]));
+}
+
+export interface ExternalChange {
+  name: string;
+  from: string | null;
+  to: string | null;
+}
+
+/** Every package whose installed version differs between the two snapshots; jeo-code is never reported. */
+export function diffInstalled(before: InstalledSnapshot, after: InstalledSnapshot): ExternalChange[] {
+  const changes: ExternalChange[] = [];
+  for (const name of new Set([...Object.keys(before), ...Object.keys(after)])) {
+    if (name === SELF_PACKAGE) continue;
+    const from = Object.hasOwn(before, name) ? before[name] ?? null : null;
+    const to = Object.hasOwn(after, name) ? after[name] ?? null : null;
+    if (from !== to) changes.push({ name, from, to });
+  }
+  return changes;
+}
+
+export function formatChangeLine(c: ExternalChange): string {
+  return `${c.name} ${c.from ?? "(not installed)"} -> ${c.to ?? "(removed)"}`;
+}
+
+const SAFE_VERSION = /^[0-9A-Za-z][0-9A-Za-z.+-]*$/;
+const SAFE_PACKAGE_NAME = new RegExp("^(@[a-z0-9][a-z0-9._-]*/)?[a-z0-9][a-z0-9._-]*$");
+
+/**
+ * One shell line per change that puts the previous state back. They are printed for a human and never run.
+ * A name or version that is not shell-safe becomes a comment so a hostile manifest cannot inject a command.
+ */
+export function formatRestoreCommands(cs: readonly ExternalChange[]): string[] {
+  return cs.map(c => {
+    if (!SAFE_PACKAGE_NAME.test(c.name)) return `# restore ${c.name.replace(/[^ -~]/g, "?")} manually`;
+    if (c.from === null) return `bun remove -g ${c.name}`;
+    return SAFE_VERSION.test(c.from) ? `bun install -g ${c.name}@${c.from}` : `# restore ${c.name} manually`;
+  });
+}
+
+const PRIMARY_TOOL = "jeopi-cli";
+
+/** `shared global unchanged: 3 packages (jeopi-cli X, a Y, b Z, ...)`; jeopi-cli leads, then ascending, at most 3 shown. */
+export function formatUnchangedSummary(after: InstalledSnapshot): string {
+  const present = Object.entries(after)
+    .filter((e): e is [string, string] => e[0] !== SELF_PACKAGE && e[1] !== null)
+    .sort(([a], [b]) => (a === PRIMARY_TOOL ? -1 : b === PRIMARY_TOOL ? 1 : a < b ? -1 : a > b ? 1 : 0));
+  const count = `${present.length} ${present.length === 1 ? "package" : "packages"}`;
+  if (present.length === 0) return `shared global unchanged: ${count}`;
+  const shown = present.slice(0, 3).map(([name, version]) => `${name} ${version}`);
+  return `shared global unchanged: ${count} (${shown.join(", ")}${present.length > 3 ? ", ..." : ""})`;
+}
+
+export type InstallOrigin = "bun-global" | "npm-global" | "unknown";
+export interface JeoOnPath {
+  path: string;
+  realpath: string;
+}
+
+/** Every executable `jeo` on PATH in PATH order, deduplicated by realpath (first PATH position wins). Nothing is executed. */
+export function listJeoOnPath(env: EnvLike = process.env, platform: NodeJS.Platform = process.platform): JeoOnPath[] {
+  if (platform === "win32") return [];
+  const found: JeoOnPath[] = [];
+  const seen = new Set<string>();
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+    if (!dir || !path.isAbsolute(dir)) continue;
+    const candidate = path.join(dir, "jeo");
+    let real: string;
+    try {
+      const stat = fs.statSync(candidate);
+      if (!stat.isFile() || (stat.mode & 0o111) === 0) continue;
+      real = fs.realpathSync(candidate);
+    } catch {
+      continue;
+    }
+    if (seen.has(real)) continue;
+    seen.add(real);
+    found.push({ path: candidate, realpath: real });
+  }
+  return found;
+}
+
+function readNpmrcPrefix(home: string | undefined): string | null | undefined {
+  if (!home) return undefined;
+  let text: string;
+  try {
+    text = fs.readFileSync(path.join(home, ".npmrc"), "utf8");
+  } catch {
+    return undefined;
+  }
+  let value: string | undefined;
+  for (const line of text.split(/\r?\n/)) {
+    const match = /^\s*prefix\s*=\s*(.*)$/.exec(line);
+    if (match) value = match[1];
+  }
+  if (value === undefined) return undefined;
+  let prefix = value.trim();
+  const quote = prefix[0];
+  if ((quote === '"' || quote === "'") && prefix.length >= 2 && prefix.endsWith(quote)) prefix = prefix.slice(1, -1);
+  else prefix = prefix.replace(/\s*[;#].*$/, "");
+  prefix = prefix.replace(/^~(?=\/|$)/, home).replace(/^\$\{?HOME\}?(?=\/|$)/, home);
+  return path.isAbsolute(prefix) ? prefix : null;
+}
+
+/**
+ * npm's global node_modules directory without running npm: `npm_config_prefix`/`NPM_CONFIG_PREFIX`, else the
+ * last `prefix =` line of `~/.npmrc`, else the first executable `npm` on PATH (only when its `lib/node_modules`
+ * really holds npm, which accepts nvm/Homebrew layouts and rejects Volta/fnm shims). Null when unknown.
+ */
+export function resolveNpmGlobalRoot(env: EnvLike = process.env, home: string | undefined = env.HOME || undefined, platform: NodeJS.Platform = process.platform): string | null {
+  if (platform === "win32") return null;
+  const fromEnv = env.npm_config_prefix || env.NPM_CONFIG_PREFIX;
+  if (fromEnv) return path.isAbsolute(fromEnv) ? path.join(fromEnv, "lib", "node_modules") : null;
+  const fromNpmrc = readNpmrcPrefix(home);
+  if (fromNpmrc !== undefined) return fromNpmrc === null ? null : path.join(fromNpmrc, "lib", "node_modules");
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+    if (!dir || !path.isAbsolute(dir)) continue;
+    const npm = path.join(dir, "npm");
+    try {
+      const stat = fs.statSync(npm);
+      if (!stat.isFile() || (stat.mode & 0o111) === 0) continue;
+    } catch {
+      continue;
+    }
+    if (path.basename(dir) !== "bin") return null;
+    const root = path.join(path.dirname(dir), "lib", "node_modules");
+    return fs.existsSync(path.join(root, "npm", "package.json")) ? root : null;
+  }
+  return null;
+}
+
+/** True when `child` is strictly inside `parent`. */
+export function isUnder(child: string, parent: string): boolean {
+  const rel = path.relative(parent, child);
+  return rel !== "" && rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+}
+
+export function classifyActiveInstall(active: string | null, roots: { bunGlobalNodeModules: string | null; npmGlobalRoot: string | null }): InstallOrigin {
+  if (active === null) return "unknown";
+  if (roots.bunGlobalNodeModules !== null && isUnder(active, roots.bunGlobalNodeModules)) return "bun-global";
+  if (roots.npmGlobalRoot !== null && isUnder(active, roots.npmGlobalRoot)) return "npm-global";
+  return "unknown";
+}
+
+function realpathIfPresent(p: string | null): string | null {
+  if (p === null) return null;
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/**
+ * Which package manager owns the `jeo` that is first on PATH, decided from paths only. A compiled binary
+ * (`currentJeoCommand` is a single element) has no package-manager install, so its origin is 'unknown'
+ * and `jeo update` never falls back to npm for it.
+ */
+export function detectInstallOrigin(o: { env?: EnvLike; home?: string; platform?: NodeJS.Platform; entry?: string; execPath?: string } = {}): {
+  origin: InstallOrigin;
+  active: string | null;
+  bunGlobalNodeModules: string | null;
+  npmGlobalRoot: string | null;
+} {
+  const env = o.env ?? process.env;
+  const platform = o.platform ?? process.platform;
+  const home = o.home ?? (env.HOME || undefined);
+  const active = listJeoOnPath(env, platform)[0]?.realpath ?? null;
+  const candidate = candidateGlobalDir(env, home, platform);
+  const bunGlobalNodeModules = candidate === null ? null : realpathIfPresent(path.join(candidate, "node_modules"));
+  const npmGlobalRoot = resolveNpmGlobalRoot(env, home, platform);
+  const compiled = currentJeoCommand(o.entry, o.execPath).length === 1;
+  const origin = compiled ? "unknown" : classifyActiveInstall(active, { bunGlobalNodeModules, npmGlobalRoot: realpathIfPresent(npmGlobalRoot) });
+  return { origin, active, bunGlobalNodeModules, npmGlobalRoot };
+}

package/src/util/shared-install-report.ts

@@ -0,0 +1,315 @@
+/**
+ * Doctor-side, read-only report on the shared bun global install that `jeo update` writes into:
+ * `bun.lock` coverage, every `jeo` on PATH with its version, leftovers a previous tool left behind
+ * (backup files, possible orphans) and where the disk space goes.
+ *
+ * Everything here only reads. Nothing is written, deleted, renamed, spawned or executed, and a
+ * symlink inside `node_modules` is never followed or read (one existence check tells a live link
+ * from a dangling one). Findings are reported for a human; nothing is repaired.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+  SELF_PACKAGE,
+  checkLockCoverage,
+  listJeoOnPath,
+  locateSharedGlobal,
+  readManifestDeps,
+  type EnvLike,
+  type GlobalSkipReason,
+  type JeoOnPath,
+  type LockCoverage,
+} from "./shared-global";
+
+export const DEFAULT_SIZE_CAP_MS = 3000;
+export const DEFAULT_SIZE_CAP_ENTRIES = 400_000;
+export const DEFAULT_ORPHAN_CAP_MANIFESTS = 5000;
+
+/** Size scans read the clock every this many entries (and before the first one). */
+const TIME_CHECK_EVERY = 256;
+const TOP_PACKAGES = 5;
+/** A `jeo` executable is the entry script inside its package: the package.json is in its directory or up to this many parents above. */
+const VERSION_WALK_PARENTS = 4;
+const BACKUP_FILE = /^package\.json\..*backup/;
+const DECLARING_FIELDS = ["dependencies", "optionalDependencies", "peerDependencies"] as const;
+
+export interface JeoOnPathEntry extends JeoOnPath {
+  version: string | null;
+  active: boolean;
+  stale: boolean;
+}
+
+export interface PossibleOrphan {
+  name: string;
+  kind: "directory" | "symlink" | "dangling-symlink";
+}
+
+export interface LeftoverReport {
+  backupFiles: string[];
+  possibleOrphans: PossibleOrphan[];
+  orphanScanComplete: boolean;
+}
+
+export interface SizeReport {
+  top: { name: string; bytes: number }[];
+  totalBytes: number;
+  scannedEntries: number;
+  complete: boolean;
+  capped: "time" | "entries" | null;
+  elapsedMs: number;
+}
+
+export interface SharedInstallReport {
+  globalDir: string | null;
+  skipped: GlobalSkipReason | null;
+  manifest: { dependencies: number; external: number } | null;
+  lockfile: LockCoverage | null;
+  jeoOnPath: JeoOnPathEntry[];
+  leftovers: LeftoverReport | null;
+  sizes: SizeReport | null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function byName(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function readPackageJson(file: string): Record<string, unknown> | null {
+  try {
+    const doc: unknown = JSON.parse(fs.readFileSync(file, "utf8"));
+    return isRecord(doc) ? doc : null;
+  } catch {
+    return null;
+  }
+}
+
+function sortedDirents(dir: string): fs.Dirent[] {
+  try {
+    return fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => byName(a.name, b.name));
+  } catch {
+    return [];
+  }
+}
+
+/** Version of the jeo-code package that owns this `jeo` entry script, read from the package.json next to it. */
+function jeoPackageVersionNear(realpath: string): string | null {
+  let dir = path.dirname(realpath);
+  for (let level = 0; level <= VERSION_WALK_PARENTS; level++) {
+    const pkg = readPackageJson(path.join(dir, "package.json"));
+    if (pkg !== null && pkg.name === SELF_PACKAGE && typeof pkg.version === "string") return pkg.version;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+/**
+ * Every `jeo` on PATH (deduplicated by realpath, PATH order) with the version of the package it belongs to.
+ * The first is the active one; a later one is stale when both versions are known and differ. Nothing is run.
+ */
+export function listJeoOnPathWithVersions(env: EnvLike = process.env, platform: NodeJS.Platform = process.platform): JeoOnPathEntry[] {
+  const found = listJeoOnPath(env, platform);
+  const versions = found.map(entry => jeoPackageVersionNear(entry.realpath));
+  const activeVersion = versions[0] ?? null;
+  return found.map((entry, index) => {
+    const version = versions[index] ?? null;
+    return {
+      ...entry,
+      version,
+      active: index === 0,
+      stale: index > 0 && version !== null && activeVersion !== null && version !== activeVersion,
+    };
+  });
+}
+
+interface InstalledPackage {
+  name: string;
+  abs: string;
+  kind: PossibleOrphan["kind"];
+}
+
+function classify(entry: fs.Dirent, abs: string): PossibleOrphan["kind"] | null {
+  if (entry.isSymbolicLink()) return fs.existsSync(abs) ? "symlink" : "dangling-symlink";
+  return entry.isDirectory() ? "directory" : null;
+}
+
+/** Non-dot packages directly inside a node_modules dir, scoped packages flattened to `@scope/name`. */
+function listPackages(nodeModules: string): InstalledPackage[] {
+  const out: InstalledPackage[] = [];
+  for (const entry of sortedDirents(nodeModules)) {
+    if (entry.name.startsWith(".")) continue;
+    const abs = path.join(nodeModules, entry.name);
+    const kind = classify(entry, abs);
+    if (kind === null) continue;
+    if (kind !== "directory" || !entry.name.startsWith("@")) {
+      out.push({ name: entry.name, abs, kind });
+      continue;
+    }
+    for (const child of sortedDirents(abs)) {
+      if (child.name.startsWith(".")) continue;
+      const childAbs = path.join(abs, child.name);
+      const childKind = classify(child, childAbs);
+      if (childKind !== null) out.push({ name: `${entry.name}/${child.name}`, abs: childAbs, kind: childKind });
+    }
+  }
+  return out;
+}
+
+/**
+ * Names that some installed package declares (dependencies, optionalDependencies, peerDependencies),
+ * collected from every package.json under node_modules, nested copies included. Symlinked packages
+ * are never descended into or read. Null when more than `cap` manifests would have to be read.
+ */
+function collectDeclared(packages: readonly InstalledPackage[], cap: number): Set<string> | null {
+  const declared = new Set<string>();
+  const pending = packages.filter(p => p.kind === "directory").map(p => p.abs);
+  let read = 0;
+  for (let abs = pending.pop(); abs !== undefined; abs = pending.pop()) {
+    if (read >= cap) return null;
+    read++;
+    const pkg = readPackageJson(path.join(abs, "package.json"));
+    if (pkg !== null) {
+      for (const field of DECLARING_FIELDS) {
+        const deps = pkg[field];
+        if (isRecord(deps)) for (const name of Object.keys(deps)) declared.add(name);
+      }
+    }
+    for (const nested of listPackages(path.join(abs, "node_modules"))) {
+      if (nested.kind === "directory") pending.push(nested.abs);
+    }
+  }
+  return declared;
+}
+
+/**
+ * Leftovers of other tools in the global dir: `package.json.*backup*` files, and installed top-level
+ * packages that neither the manifest nor any installed package declares ("possible orphans"; a dot-prefixed
+ * entry is never reported). When the declared-name scan would exceed `capManifests` no orphan is reported
+ * and `orphanScanComplete` is false.
+ */
+export function findStaleLeftovers(dir: string, manifestNames: readonly string[], capManifests: number = DEFAULT_ORPHAN_CAP_MANIFESTS): LeftoverReport {
+  const backupFiles = sortedDirents(dir)
+    .filter(entry => entry.isFile() && BACKUP_FILE.test(entry.name))
+    .map(entry => entry.name);
+  const nodeModules = path.join(dir, "node_modules");
+  const inManifest = new Set(manifestNames);
+  const packages = listPackages(nodeModules);
+  const candidates = packages.filter(p => !inManifest.has(p.name));
+  if (candidates.length === 0) return { backupFiles, possibleOrphans: [], orphanScanComplete: true };
+  const declared = collectDeclared(packages, capManifests);
+  if (declared === null) return { backupFiles, possibleOrphans: [], orphanScanComplete: false };
+  const possibleOrphans = candidates
+    .filter(p => !declared.has(p.name))
+    .map(({ name, kind }): PossibleOrphan => ({ name, kind }))
+    .sort((a, b) => byName(a.name, b.name));
+  return { backupFiles, possibleOrphans, orphanScanComplete: true };
+}
+
+interface WalkFrame {
+  dir: string;
+  level: "root" | "scope" | "package";
+  scope: string;
+  /** Top-level package the directory belongs to; null for dot entries and stray files, which only count toward the total. */
+  pkg: string | null;
+}
+
+/**
+ * Apparent bytes under `dir/node_modules`, attributed to the top-level package (scoped flattened) that holds them.
+ * Symlinks count their own size and are never followed; a directory counts as one entry and no bytes. The walk
+ * stops at the entry cap (checked on every entry) or the time cap (checked before the first entry and every 256
+ * entries); a stopped scan returns lower bounds with `complete: false`.
+ */
+export function sizeReport(dir: string, o: { now?: () => number; capMs?: number; capEntries?: number } = {}): SizeReport {
+  const now = o.now ?? Date.now;
+  const capMs = o.capMs ?? DEFAULT_SIZE_CAP_MS;
+  const capEntries = o.capEntries ?? DEFAULT_SIZE_CAP_ENTRIES;
+  const started = now();
+  const bytesByPackage = new Map<string, number>();
+  let totalBytes = 0;
+  let scanned = 0;
+  let capped: SizeReport["capped"] = null;
+  const stack: WalkFrame[] = [{ dir: path.join(dir, "node_modules"), level: "root", scope: "", pkg: null }];
+  walk: for (let frame = stack.pop(); frame !== undefined; frame = stack.pop()) {
+    for (const entry of sortedDirents(frame.dir)) {
+      if (scanned >= capEntries) {
+        capped = "entries";
+        break walk;
+      }
+      if (scanned % TIME_CHECK_EVERY === 0 && now() - started > capMs) {
+        capped = "time";
+        break walk;
+      }
+      scanned++;
+      const abs = path.join(frame.dir, entry.name);
+      const isDir = entry.isDirectory();
+      let pkg = frame.pkg;
+      if (frame.level === "root") pkg = entry.name.startsWith(".") || (!isDir && !entry.isSymbolicLink()) ? null : entry.name;
+      else if (frame.level === "scope") pkg = entry.name.startsWith(".") ? null : `${frame.scope}/${entry.name}`;
+      if (isDir) {
+        if (frame.level === "root" && entry.name.startsWith("@")) {
+          stack.push({ dir: abs, level: "scope", scope: entry.name, pkg: null });
+        } else {
+          stack.push({ dir: abs, level: "package", scope: "", pkg });
+          if (pkg !== null && !bytesByPackage.has(pkg)) bytesByPackage.set(pkg, 0);
+        }
+        continue;
+      }
+      let size = 0;
+      try {
+        size = fs.lstatSync(abs).size;
+      } catch {
+        // A file that vanished mid-scan counts as zero bytes.
+      }
+      totalBytes += size;
+      if (pkg !== null) bytesByPackage.set(pkg, (bytesByPackage.get(pkg) ?? 0) + size);
+    }
+  }
+  const top = [...bytesByPackage]
+    .map(([name, bytes]) => ({ name, bytes }))
+    .sort((a, b) => b.bytes - a.bytes || byName(a.name, b.name))
+    .slice(0, TOP_PACKAGES);
+  return { top, totalBytes, scannedEntries: scanned, complete: capped === null, capped, elapsedMs: now() - started };
+}
+
+/**
+ * One read-only snapshot for `jeo doctor`. The `jeo` executables on PATH are always listed; when no usable
+ * bun global exists the report says why (`skipped`) and leaves the other sections null. File-system errors
+ * degrade to empty findings instead of throwing.
+ */
+export function collectSharedInstallReport(
+  o: {
+    env?: EnvLike;
+    home?: string;
+    platform?: NodeJS.Platform;
+    entry?: string;
+    execPath?: string;
+    now?: () => number;
+    sizeCapMs?: number;
+    sizeCapEntries?: number;
+    orphanCapManifests?: number;
+  } = {},
+): SharedInstallReport {
+  const env = o.env ?? process.env;
+  const platform = o.platform ?? process.platform;
+  const jeoOnPath = listJeoOnPathWithVersions(env, platform);
+  const located = locateSharedGlobal({ env, home: o.home, platform, entry: o.entry, execPath: o.execPath });
+  const manifest = located.ok ? readManifestDeps(located.dir) : null;
+  if (!located.ok || manifest === null || !manifest.ok) {
+    const skipped: GlobalSkipReason = located.ok ? "manifest-unreadable" : located.reason;
+    return { globalDir: null, skipped, manifest: null, lockfile: null, jeoOnPath, leftovers: null, sizes: null };
+  }
+  const { names, external } = manifest.deps;
+  return {
+    globalDir: located.dir,
+    skipped: null,
+    manifest: { dependencies: names.length, external: external.length },
+    lockfile: checkLockCoverage(located.dir, external),
+    jeoOnPath,
+    leftovers: findStaleLeftovers(located.dir, names, o.orphanCapManifests),
+    sizes: sizeReport(located.dir, { now: o.now, capMs: o.sizeCapMs, capEntries: o.sizeCapEntries }),
+  };
+}