disk-space-saviour 0.17.0 → 0.18.0

package/src/liveness.js

@@ -8,7 +8,9 @@
  * - a process holds a file, working directory, or executable inside the path
  *   (`/proc/<pid>/{fd,cwd,exe}` on Linux, `lsof` on macOS).
  * - a command argument names a path inside the item (including scripts
- *   whose interpreter has already closed its input descriptor).
+ *   whose interpreter has already closed its input descriptor);
+ * - a directory inside the item is on a process's `PATH`, so the process
+ *   may start a program from it at any time.
  *
  * The cleaner refreshes the probe right before acting on each item.
  */
@@ -20,6 +22,44 @@ import { formatDuration } from './units.js';
 
 const PROC_COMM_LIMIT = 15;
 
+/** Bun subcommands that read or write the install cache. */
+const BUN_PACKAGE_COMMANDS = new Set([
+  'install',
+  'i',
+  'add',
+  'a',
+  'remove',
+  'rm',
+  'update',
+  'upgrade',
+  'outdated',
+  'link',
+  'unlink',
+  'pm',
+  'x',
+  'create',
+  'c',
+  'init',
+  'patch',
+  'publish',
+  'audit',
+  'why',
+  'info',
+]);
+
+function isBun(proc) {
+  return Boolean(matchingName(proc, ['bun', 'bunx']));
+}
+
+function bunPackageCommand(proc) {
+  const args = processArgs(proc);
+  if (path.posix.basename(args[0] ?? '') === 'bunx' || proc.name === 'bunx') {
+    return true;
+  }
+  const command = args.slice(1).find((arg) => !arg.startsWith('-'));
+  return BUN_PACKAGE_COMMANDS.has(command);
+}
+
 function uncertaintyRoots(proc) {
   const roots = processArgs(proc).flatMap((arg) => {
     const value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : arg;
@@ -182,6 +222,7 @@ export class LivenessProbe {
     const processes = await this.env.processes().catch(() => null);
     this.listed = processes !== null;
     this.processes = processes ?? [];
+    this.bunCacheUsers = await this.#bunCacheUsers();
     this.probeError =
       (processes === null || this.openPaths === null) &&
       (this.env.platform === 'linux' || this.env.platform === 'darwin');
@@ -191,6 +232,49 @@ export class LivenessProbe {
     this.pathOwners.clear();
   }
 
+  /**
+   * Pids of Bun processes that may use the install cache: package commands,
+   * and anything else (scripts, tests, the REPL) without a `node_modules`
+   * directory above its working directory, because Bun then auto-installs
+   * from the cache. A long-running script of an installed project does not
+   * read the cache, so it does not keep the cache busy.
+   */
+  async #bunCacheUsers() {
+    const users = new Set();
+    const installed = new Map();
+    const hasModules = async (dir) => {
+      if (!installed.has(dir)) {
+        installed.set(
+          dir,
+          Boolean(
+            await this.env.exists?.(this.env.path.join(dir, 'node_modules'))
+          )
+        );
+      }
+      return installed.get(dir);
+    };
+    for (const proc of this.processes) {
+      if (!isBun(proc)) {
+        continue;
+      }
+      if (bunPackageCommand(proc) || !proc.cwd || !this.env.exists) {
+        users.add(proc.pid);
+        continue;
+      }
+      let found = false;
+      for (const dir of [proc.cwd, ...ancestors(proc.cwd, this.env.path)]) {
+        if (await hasModules(dir)) {
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        users.add(proc.pid);
+      }
+    }
+    return users;
+  }
+
   /** Processes of the last refresh, or null when they could not be listed. */
   processList() {
     return this.listed ? this.processes : null;
@@ -269,6 +353,13 @@ export class LivenessProbe {
       ) {
         continue;
       }
+      if (
+        item.rule === 'bun-cache' &&
+        isBun(proc) &&
+        !this.bunCacheUsers?.has(proc.pid)
+      ) {
+        continue;
+      }
       const name = matchingName(proc, names);
       if (!name) {
         continue;
@@ -291,10 +382,7 @@ export class LivenessProbe {
       return null;
     }
     const pathApi = this.env.path;
-    const targets = paths.flatMap((target) => {
-      const real = this.realPaths.get(target);
-      return real && real !== target ? [target, real] : [target];
-    });
+    const targets = this.withRealPaths(paths);
     for (const open of this.openPaths) {
       for (const target of targets) {
         if (isWithin(open, target, pathApi)) {
@@ -340,6 +428,26 @@ export class LivenessProbe {
     return null;
   }
 
+  /** `paths` plus their resolved forms, as processes report paths. */
+  withRealPaths(paths) {
+    return paths.flatMap((target) => {
+      const real = this.realPaths.get(target);
+      return real && real !== target ? [target, real] : [target];
+    });
+  }
+
+  searchPathUsage(paths) {
+    const targets = this.withRealPaths(paths);
+    for (const proc of this.processes) {
+      for (const dir of proc.searchPath ?? []) {
+        if (targets.some((target) => isWithin(dir, target, this.env.path))) {
+          return `on the PATH of ${proc.name || 'a process'} (pid ${proc.pid}): ${dir}`;
+        }
+      }
+    }
+    return null;
+  }
+
   uncertainUsage(paths) {
     for (const proc of this.env.unreadableProcesses ?? []) {
       const args = processArgs(proc);
@@ -399,14 +507,28 @@ export class LivenessProbe {
     const paths = checks.perPath ? [] : (item.paths ?? []);
     return (
       this.installationBlocker(item.paths ?? []) ??
-      (this.probeError
-        ? `cannot verify process and open-file activity${this.env.probeDiagnostic ? `: ${this.env.probeDiagnostic}` : ''}`
-        : null) ??
+      this.probeBlocker() ??
       (checks.mtime === false ? null : this.recentWrite(item.newestMtimeMs)) ??
       this.runningTool(checks.busy, checks.cwd, item) ??
+      this.processUsage(paths) ??
+      this.uncertainUsage(item.paths ?? [])
+    );
+  }
+
+  probeBlocker() {
+    if (!this.probeError) {
+      return null;
+    }
+    const diagnostic = this.env.probeDiagnostic;
+    return `cannot verify process and open-file activity${diagnostic ? `: ${diagnostic}` : ''}`;
+  }
+
+  /** Open files, command arguments and PATH entries inside the paths. */
+  processUsage(paths) {
+    return (
       this.openInside(paths) ??
       this.commandUsage(paths) ??
-      this.uncertainUsage(item.paths ?? [])
+      this.searchPathUsage(paths)
     );
   }
 

package/src/report.js

@@ -305,6 +305,52 @@ function errorsSection(errors) {
   ];
 }
 
+const TIMING_LIMIT = 5;
+
+function phaseList(phases) {
+  return phases
+    .map(
+      (phase) =>
+        `${phase.phase} ${(phase.ms / 1000).toFixed(1)}s${phase.count > 1 ? ` ×${phase.count}` : ''}`
+    )
+    .join(', ');
+}
+
+/**
+ * Slowest cleanup phases and items. `audit.timings` is a live PhaseTimer
+ * while cleaning and a plain array once read back from JSON.
+ */
+function auditTimingLines(audit, { verbose }) {
+  const phases = audit.timings?.toJSON?.() ?? audit.timings ?? [];
+  const items = audit.entries
+    .filter((entry) => entry.durationMs > 0)
+    .sort((a, b) => b.durationMs - a.durationMs);
+  const limit = verbose ? Infinity : TIMING_LIMIT;
+  const lines = [];
+  if (phases.length > 0) {
+    lines.push(`  slowest phases: ${phaseList(phases.slice(0, limit))}`);
+  }
+  for (const entry of items.slice(0, limit)) {
+    lines.push(
+      `  ${(entry.durationMs / 1000).toFixed(1)}s  ${entry.rule}  ${entry.path ?? entry.description}`
+    );
+  }
+  return lines.length > 0 ? ['', 'TIMINGS', ...lines] : [];
+}
+
+/**
+ * The slowest phases of each environment, so bottlenecks are visible
+ * without debug flags.
+ */
+function timingLines(report, { verbose }) {
+  return report.environments
+    .filter((env) => env.timings?.length > 0)
+    .map((env) => {
+      const phases = verbose ? env.timings : env.timings.slice(0, TIMING_LIMIT);
+      return `  ${env.label} slowest phases: ${phaseList(phases)}`;
+    });
+}
+
 /**
  * Renders a scan report.
  * @param {object} report
@@ -352,6 +398,10 @@ export function formatReport(report, options = {}) {
   lines.push(...dockerSection(report));
   lines.push(...errorsSection(report.errors));
   lines.push(...totalsSection(report));
+  const timings = timingLines(report, options);
+  if (timings.length > 0) {
+    lines.push('', 'TIMINGS', ...timings);
+  }
   return lines.join('\n');
 }
 
@@ -445,6 +495,7 @@ export function formatAudit(audit, options = {}) {
   }
   lines.push('', 'Per environment:', ...environmentLines(audit.environments));
   lines.push(...healthLines(audit.health));
+  lines.push(...auditTimingLines(audit, options));
   lines.push(
     '',
     audit.dryRun

package/src/rules/ecosystems.js

@@ -8,9 +8,8 @@
  *
  * `projects` are directories inside project trees, recognised by name plus a
  * marker file next to them (`markers`), inside them (`selfMarkers`), or next
- * to their parent (`parentMarkers`, with `parentName`). Kind `cache` is always
- * `safe`; `build` and `dependencies` are `moderate` after the project has been
- * inactive for the configured number of days and `aggressive` otherwise.
+ * to their parent (`parentMarkers`, with `parentName`). All kinds (`cache`,
+ * `build`, `dependencies`) are `safe` whenever nothing is using them.
  *
  * `busy` lists process names that, when running (inside the project for
  * project directories), mean the tool may be using the directory right now.
@@ -71,7 +70,9 @@ export const ECOSYSTEMS = [
         description: 'Bun install cache',
         paths: ['~/.bun/install/cache'],
         native: { tool: 'bun', argv: ['bun', 'pm', 'cache', 'rm'] },
-        busy: ['bun'],
+        // Only package commands and auto-installing scripts read the cache
+        // (see LivenessProbe.refresh).
+        busy: ['bun', 'bunx'],
       },
       {
         id: 'deno-cache',

package/src/rules/other.js

@@ -349,8 +349,11 @@ export const OTHER_RULES = [
     ecosystem: 'agents',
     description: 'abandoned Codex runtime install staging directories',
     paths: ['~/.cache/codex-runtimes/codex-runtime-install-*'],
+    // The Codex daemon runs for days, so a running `codex` says nothing
+    // about a staging directory: an install in progress writes to it and
+    // holds its files open, which the activity window and open-file checks
+    // catch.
     minAge: 'stale',
-    busy: ['codex'],
   },
   {
     id: 'claude-cli-mcp-logs',

package/src/rules/versions.js

@@ -6,6 +6,11 @@
  * - the newest installed version,
  * - in use by a running process (checked by the liveness layer).
  *
+ * `refsPickNewest` makes a partial ref keep only the newest install it
+ * matches (nvm runs the newest 20.x for `20`); otherwise it keeps them all.
+ * `globalPackages` blocks versions holding packages the user installed
+ * globally, which reinstalling the version would not bring back.
+ *
  * `versionOf(dirPath)` maps an install directory to the version string that
  * defaults and pin files are compared with (see `versionMatches`).
  */
@@ -112,6 +117,16 @@ export const VERSION_RULES = [
     busy: ['claude'],
     recheck: true,
   },
+  {
+    id: 'codex-daemon-releases',
+    ecosystem: 'agents',
+    manager: 'Codex',
+    description: 'Codex app-server daemon release',
+    dirs: ['~/.codex/packages/app-server-daemon/releases/*'],
+    defaultLinks: ['~/.codex/packages/app-server-daemon/current'],
+    busy: ['codex'],
+    recheck: true,
+  },
   {
     id: 'copilot-cli-versions',
     ecosystem: 'agents',
@@ -133,6 +148,14 @@ export const VERSION_RULES = [
     aliasDir: '~/.nvm/alias',
     defaults: [{ path: '~/.nvm/alias/default', parse: firstLines }],
     projectFiles: { '.nvmrc': firstLines, '.node-version': firstLines },
+    refsPickNewest: true,
+    globalPackages: {
+      dir: 'lib/node_modules',
+      // Bundled with Node.js, or a use-m cache (`<name>-v-<version>`) that
+      // use-m installs again on first use.
+      regenerable: (name) =>
+        name === 'npm' || name === 'corepack' || /^[^@][^/]*-v-./.test(name),
+    },
     busy: ['node'],
   },
   {

package/src/scan.js

@@ -32,6 +32,7 @@ import {
   ScanIndex,
   scopeKey,
 } from './scan-state.js';
+import { PhaseTimer, timed } from './timings.js';
 
 export const SCANNERS = {
   projects: scanProjects,
@@ -266,6 +267,12 @@ export async function scanEnvironment(env, options, extra = {}) {
   }
 }
 
+/** Phase timings of an environment, started on its first scan. */
+function environmentTimings(env) {
+  env.timings ??= new PhaseTimer();
+  return env.timings;
+}
+
 async function scanEnvironmentScoped(
   env,
   options,
@@ -275,11 +282,14 @@ async function scanEnvironmentScoped(
   stage
 ) {
   const errors = extra.errors ?? [];
-  const context = await environmentContext(env, options, extra);
+  const context = await environmentTimings(env).measure('context', () =>
+    environmentContext(env, options, extra)
+  );
+  context.timings = env.timings;
   context.emit = (item) => found.set(item.id, item);
   let stopped = false;
   const ready = async (items) => {
-    await attributeStorage(env, items);
+    await env.timings.measure('storage', () => attributeStorage(env, items));
     for (const item of items) {
       for (const target of item.paths) {
         block(item, env.scanPolicy.removalReason(target));
@@ -324,7 +334,9 @@ async function scanEnvironmentScoped(
     const started = Date.now();
     const previous = new Set(found.keys());
     try {
-      const entries = await scanner(context);
+      const entries = await env.timings.measure(`scanner:${name}`, () =>
+        scanner(context)
+      );
       for (const item of entries) {
         context.emit(item);
       }
@@ -480,6 +492,7 @@ function envDescriptor(env, depth, chain) {
     hint: env.probeHint ?? null,
     scanStatus: env.scanStatus ?? null,
     layerSource: env.writableLayer?.source ?? null,
+    timings: env.timings?.toJSON() ?? [],
   };
 }
 
@@ -590,6 +603,7 @@ async function scanScoped(input) {
   resetWritableLayers(env.executor);
   env.writableLayer = null;
   env.scanPolicy = null;
+  env.timings = new PhaseTimer();
   await configureScanPolicy(env, options);
   await configureContainerHost(
     env,
@@ -603,7 +617,9 @@ async function scanScoped(input) {
   const docker =
     env.scanStatus === 'goal-reached'
       ? null
-      : await dockerSection(env, options, errors);
+      : await timed(env.timings, 'docker', () =>
+          dockerSection(env, options, errors)
+        );
   blockMountedHostItems(hostItems, docker?.bindMounts ?? [], env.path);
   const items = filterItems(
     [...hostItems, ...(docker?.items ?? [])],
@@ -615,7 +631,10 @@ async function scanScoped(input) {
   for (const inner of docker?.environments ?? []) {
     environments.push(inner);
   }
-  environments[0] = await withDisk(env, environments[0]);
+  environments[0] = await timed(env.timings, 'disk', () =>
+    withDisk(env, environments[0])
+  );
+  environments[0].timings = env.timings.toJSON();
   const report = buildReport({
     options,
     env,

package/src/scanners/global.js

@@ -14,6 +14,7 @@ import { expandGlobPaths, expandRulePath, isWithin } from '../paths.js';
 import { olderThan, scanTimeBusy, resolvePaths } from './common.js';
 import { configuredPattern } from '../env/cache-roots.js';
 import { TOOLCHAIN_CACHE_RULES } from '../rules/toolchains.js';
+import { timed } from '../timings.js';
 
 export const GLOBAL_RULES = [
   ...CACHE_RULES,
@@ -242,9 +243,11 @@ export async function scanGlobal(context, { rules = GLOBAL_RULES } = {}) {
       patterns: rulePatterns(env, rule, base),
     }))
   );
-  const matches = await expandGlobPaths(
-    env,
-    planned.flatMap((entry) => entry.patterns)
+  const matches = await timed(context.timings, 'global:expand', () =>
+    expandGlobPaths(
+      env,
+      planned.flatMap((entry) => entry.patterns)
+    )
   );
   const typedPaths = planned
     .filter(
@@ -253,7 +256,9 @@ export async function scanGlobal(context, { rules = GLOBAL_RULES } = {}) {
     .flatMap(({ patterns }) =>
       patterns.flatMap((pattern) => matches.get(pattern) ?? [])
     );
-  const stats = await env.statMany([...new Set(typedPaths)]);
+  const stats = await timed(context.timings, 'global:stat', () =>
+    env.statMany([...new Set(typedPaths)])
+  );
   const found = [];
   const seen = new Set();
   for (const { rule, base, patterns } of planned) {
@@ -263,7 +268,11 @@ export async function scanGlobal(context, { rules = GLOBAL_RULES } = {}) {
 
     const accepted = [];
     for (const target of candidates) {
-      if (!(await acceptedPath(env, rule, target, stats))) {
+      if (
+        !(await timed(context.timings, 'global:accept', () =>
+          acceptedPath(env, rule, target, stats)
+        ))
+      ) {
         continue;
       }
       accepted.push(target);
@@ -274,9 +283,11 @@ export async function scanGlobal(context, { rules = GLOBAL_RULES } = {}) {
       found.push({ rule, base, paths });
     }
   }
-  await resolvePaths(
-    context,
-    found.flatMap((entry) => entry.paths)
+  await timed(context.timings, 'global:resolve', () =>
+    resolvePaths(
+      context,
+      found.flatMap((entry) => entry.paths)
+    )
   );
   const items = scanItems(context);
   // Deliver cheap native measurements before rules needing recursive activity
@@ -284,20 +295,27 @@ export async function scanGlobal(context, { rules = GLOBAL_RULES } = {}) {
   found.sort(
     (a, b) => Number(requiresMtime(a.rule)) - Number(requiresMtime(b.rule))
   );
+  // The report drops items below `minSize`; skipping them here saves their
+  // liveness checks (Telegram media alone can hold 100k small files). In a
+  // container the writable layer re-measures sizes later, so all are kept.
+  const large = (entry) =>
+    Boolean(env.writableLayer) ||
+    entry.usage.bytes >= (options.minSizeBytes ?? 0);
   for (const { rule, base, paths } of found) {
-    const usages = await env.usageMany(paths, {
-      mtime: requiresMtime(rule),
-      cache: true,
-    });
+    const usages = await timed(context.timings, 'global:measure', () =>
+      env.usageMany(paths, { mtime: requiresMtime(rule), cache: true })
+    );
     const accept = ageFilter(context, rule);
     const measured = paths
       .map((target) => ({ path: target, usage: usages.get(target) }))
       .filter((entry) => entry.usage && accept(entry.usage));
     const groups = rule.aggregate
       ? [measured]
-      : measured.map((entry) => [entry]);
+      : measured.filter(large).map((entry) => [entry]);
     for (const group of groups.filter((g) => g.length > 0)) {
-      const item = await buildItem(context, rule, base, group);
+      const item = await timed(context.timings, 'global:item', () =>
+        buildItem(context, rule, base, group)
+      );
       items.push(item);
       if ((await context.ready?.([item])) === false) {
         return items;