disk-space-saviour 0.17.0 → 0.19.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/apps.js

@@ -167,9 +167,13 @@ export function expandChromiumCaches(rules) {
             CACHE_LEAVES.map((leaf) => `${p}/${leaf}`)
           ),
           ...roots.flatMap((p) =>
-            ['GrShaderCache', 'ShaderCache', 'component_crx_cache'].map(
-              (leaf) => `${p}/${leaf}`
-            )
+            [
+              'GrShaderCache',
+              'ShaderCache',
+              'GraphiteDawnCache',
+              'component_crx_cache',
+              'extensions_crx_cache',
+            ].map((leaf) => `${p}/${leaf}`)
           ),
         ]),
       ],

package/src/rules/downloads.js

@@ -0,0 +1,175 @@
+import { CACHE_LEAVES } from './apps.js';
+
+/**
+ * Files an application downloads or stages for itself and fetches again on
+ * demand: staged updates, language servers, toolchain archives, app bundle
+ * clones and caches outside the usual cache folders. Installed applications
+ * and the data they read are never matched.
+ */
+const openaiProfiles = [
+  '~/Library/Caches/com.openai.atlas/browser-data/host/*',
+  '~/Library/Caches/Codex/*',
+];
+const zedRoots = ['~/Library/Application Support/Zed', '~/.local/share/zed'];
+
+export const DOWNLOAD_RULES = [
+  {
+    id: 'chromium-code-sign-clones',
+    ecosystem: 'browsers',
+    scope: 'tmp',
+    description:
+      'Chromium app bundle clones left by exited browsers (an update makes them full copies)',
+    // Chrome clones its bundle into the per-user `X` directory next to
+    // `$TMPDIR` at launch and removes the clone when it exits. A running
+    // browser maps the executables of its clone, so the open-file check
+    // keeps every clone in use: a browser name would block orphans forever.
+    paths: ['{TMP}/../X/*.code_sign_clone/code_sign_clone.*'],
+    directoryOnly: true,
+    minAge: 'stale',
+    busy: [],
+  },
+  {
+    id: 'chrome-on-device-models',
+    ecosystem: 'browsers',
+    description: 'superseded Chrome on-device AI model versions',
+    paths: [
+      '~/Library/Application Support/Google/Chrome/OptGuideOnDeviceModel/*',
+      '~/.config/google-chrome/OptGuideOnDeviceModel/*',
+      '{LOCALAPPDATA}/Google/Chrome/User Data/OptGuideOnDeviceModel/*',
+    ],
+    versionPattern: /^(?<version>\d+(?:\.\d+){1,3})$/,
+    minAge: 'stale',
+    busy: [],
+  },
+  {
+    id: 'google-updater-downloads',
+    ecosystem: 'system',
+    description: 'Google Updater downloaded installers',
+    paths: [
+      '~/Library/Application Support/Google/GoogleUpdater/crx_cache',
+      '{LOCALAPPDATA}/Google/GoogleUpdater/crx_cache',
+    ],
+    minAge: 'stale',
+    busy: ['GoogleUpdater'],
+  },
+  {
+    id: 'openai-app-caches',
+    ecosystem: 'apps',
+    description: 'ChatGPT Atlas and Codex app browser caches',
+    paths: openaiProfiles.flatMap((profile) =>
+      CACHE_LEAVES.map((leaf) => `${profile}/${leaf}`)
+    ),
+    busy: ['ChatGPT Atlas', 'Codex'],
+  },
+  {
+    id: 'electron-downloads',
+    ecosystem: 'javascript',
+    description: 'Electron and electron-builder downloaded archives',
+    paths: [
+      '~/Library/Caches/electron',
+      '~/Library/Caches/electron-builder',
+      '~/.cache/electron',
+      '~/.cache/electron-builder',
+      '{LOCALAPPDATA}/electron/Cache',
+      '{LOCALAPPDATA}/electron-builder/Cache',
+    ],
+    minAge: 'stale',
+    busy: ['electron-builder', 'electron-forge'],
+  },
+  {
+    id: 'bun-transpiler-cache',
+    ecosystem: 'javascript',
+    description: 'Bun runtime transpiler cache',
+    // Bun validates every entry against its source and transpiles again on
+    // a miss, so only open files hold the cache back.
+    paths: ['~/Library/Caches/bun/@t@', '~/.cache/bun/@t@'],
+    busy: [],
+  },
+  {
+    id: 'docker-desktop-update-downloads',
+    ecosystem: 'apps',
+    description: 'Docker Desktop updates downloaded but not installed',
+    paths: ['~/Library/Application Support/com.docker.install/in_progress'],
+    minAge: 'stale',
+    busy: ['Docker Desktop', 'com.docker.backend', 'Docker'],
+  },
+  {
+    id: 'docker-desktop-update-images',
+    ecosystem: 'apps',
+    scope: 'tmp',
+    description: 'Docker Desktop update disk images',
+    paths: ['{TMP}/DockerDesktopUpdates/*'],
+    minAge: 'stale',
+    busy: ['Docker Desktop', 'com.docker.backend', 'Docker'],
+  },
+  {
+    id: 'warp-staged-updates',
+    ecosystem: 'apps',
+    description: 'Warp updates staged for the next restart',
+    paths: ['~/Library/Application Support/dev.warp.Warp-*/autoupdate/*'],
+    minAge: 'stale',
+    // Warp applies the staged bundle when it quits, so it stays while Warp
+    // runs. The process names are those of the Stable and Preview builds.
+    busy: ['stable', 'preview', 'Warp'],
+  },
+  {
+    id: 'zed-downloads',
+    ecosystem: 'ide',
+    description: 'Zed downloaded Node.js, language servers and Copilot',
+    paths: zedRoots.flatMap((root) =>
+      ['node', 'languages', 'copilot'].map((leaf) => `${root}/${leaf}`)
+    ),
+    busy: ['zed', 'Zed', 'zed-editor'],
+  },
+  {
+    id: 'tree-sitter-downloads',
+    ecosystem: 'c-cpp',
+    description: 'tree-sitter CLI downloaded WASI SDK, Binaryen and parsers',
+    paths: ['~/.cache/tree-sitter', '~/Library/Caches/tree-sitter'],
+    busy: ['tree-sitter'],
+  },
+  {
+    id: 'codex-plugin-staging',
+    ecosystem: 'agents',
+    description: 'abandoned Codex plugin and marketplace install staging',
+    paths: [
+      '~/.codex/plugins/..plugin-appserver.staging-*',
+      '~/.codex/plugins/.marketplace-plugin-source-staging/*',
+      '~/.codex/plugins/.remote-plugin-install-staging/*',
+      '~/.codex/.tmp/marketplaces/.staging/*',
+    ],
+    // The Codex daemon runs for days; an install in progress writes to its
+    // staging directory, which the activity window and open files catch.
+    minAge: 'stale',
+  },
+  {
+    id: 'clang-module-cache',
+    ecosystem: 'c-cpp',
+    description: 'Clang and Swift implicit module cache',
+    scope: 'tmp',
+    paths: [
+      '{TMP}/../C/clang/ModuleCache',
+      '{TMP}/../C/org.llvm.clang*/ModuleCache',
+    ],
+    // A build in another directory still reads the cache, which the
+    // activity window and open files catch.
+    minAge: 'stale',
+    busy: ['clang', 'clang++', 'swift-frontend', 'swiftc', 'xcodebuild'],
+  },
+  {
+    id: 'crashpad-reports',
+    ecosystem: 'system',
+    description: 'Chromium and Electron app crash reports already processed',
+    tier: 'moderate',
+    aggregate: true,
+    paths: [
+      '~/Library/Application Support/*/Crashpad/completed/*',
+      ...['Google', 'Yandex', 'BraveSoftware'].map(
+        (vendor) =>
+          `~/Library/Application Support/${vendor}/*/Crashpad/completed/*`
+      ),
+      '~/.config/*/Crashpad/completed/*',
+    ],
+    minAge: 'stale',
+  },
+];

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

@@ -107,6 +107,9 @@ export const OTHER_RULES = [
       '~/Library/Application Support/Code/Cache',
       '~/Library/Application Support/Code/CachedData',
       '~/Library/Application Support/Code/CachedExtensionVSIXs',
+      '~/Library/Application Support/Code/WebStorage/*/CacheStorage',
+      '~/.config/Code/WebStorage/*/CacheStorage',
+      '{APPDATA}/Code/WebStorage/*/CacheStorage',
       '~/.vscode-server/data/CachedExtensionVSIXs',
       '~/.vscode-server/data/logs',
       '~/.cursor-server/data/CachedExtensionVSIXs',
@@ -349,8 +352,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,