disk-space-saviour 0.19.0 → 0.21.0

package/src/liveness.js

@@ -212,6 +212,7 @@ export class LivenessProbe {
     this.realPaths = new Map();
     this.pathOwners = new Map();
     this.pathStats = new Map();
+    this.inodes = new Map();
   }
 
   async refresh(force = false) {
@@ -230,6 +231,50 @@ export class LivenessProbe {
     this.realPaths.clear();
     this.pathStats.clear();
     this.pathOwners.clear();
+    this.inodes.clear();
+  }
+
+  /**
+   * Inodes of `executables` and of the open files that share their names,
+   * because a process running a hard link of an executable reports
+   * whichever path it was started from.
+   * @param {string[]} [executables]
+   */
+  async resolveExecutables(executables = []) {
+    if (executables.length === 0) {
+      return;
+    }
+    const names = new Set(
+      executables.map((target) => this.env.path.basename(target))
+    );
+    const missing = [
+      ...executables,
+      ...[...(this.openPaths ?? [])].filter((open) =>
+        names.has(this.env.path.basename(open))
+      ),
+    ].filter((target) => !this.inodes.has(target));
+    const stats = await Promise.all(
+      missing.map((target) => this.env.stat(target))
+    );
+    missing.forEach((target, index) =>
+      this.inodes.set(target, stats[index]?.inode ?? null)
+    );
+  }
+
+  /** A process running one of `executables` under any of its links. */
+  executableUsage(executables = []) {
+    for (const target of executables) {
+      const inode = this.inodes.get(target);
+      if (!inode) {
+        continue;
+      }
+      for (const open of this.openPaths ?? []) {
+        if (open !== target && this.inodes.get(open) === inode) {
+          return `in use: ${open} is ${target}`;
+        }
+      }
+    }
+    return null;
   }
 
   /**
@@ -511,6 +556,7 @@ export class LivenessProbe {
       (checks.mtime === false ? null : this.recentWrite(item.newestMtimeMs)) ??
       this.runningTool(checks.busy, checks.cwd, item) ??
       this.processUsage(paths) ??
+      this.executableUsage(checks.executables) ??
       this.uncertainUsage(item.paths ?? [])
     );
   }

package/src/playwright-registry.js

@@ -0,0 +1,77 @@
+/**
+ * Browser revisions that installed Playwright packages still launch.
+ *
+ * Playwright records every package it installed browsers for as a file in
+ * `<registry>/.links/` holding that package's directory, and the package's
+ * `browsers.json` names the revisions it launches. Playwright's own cleanup
+ * keeps a revision while a linked package that still exists names it; dss
+ * keeps the same revisions, so deleting one never breaks an installed
+ * project until its next `playwright install`.
+ */
+
+/** Directory of a registry revision: `chromium-headless-shell` → `chromium_headless_shell-1248`. */
+export function browserDirName(name, revision) {
+  return `${name.replace(/-/g, '_')}-${revision}`;
+}
+
+/** Revision directories one `browsers.json` names, platform overrides included. */
+export function requiredDirs(text) {
+  const browsers = JSON.parse(text)?.browsers;
+  if (!Array.isArray(browsers)) {
+    throw new Error('no browsers list');
+  }
+  return browsers.flatMap((browser) =>
+    [browser.revision, ...Object.values(browser.revisionOverrides ?? {})]
+      .filter(Boolean)
+      .map((revision) => browserDirName(browser.name, revision))
+  );
+}
+
+/**
+ * Maps each revision directory name to the linked packages that need it;
+ * `unreadable` lists links whose package exists but cannot be read.
+ */
+export async function playwrightUsers(env, registry) {
+  const users = new Map();
+  const unreadable = [];
+  for (const link of await env.list(env.path.join(registry, '.links'))) {
+    const pkg = (await env.readText(link.path))?.trim();
+    if (!pkg) {
+      unreadable.push(link.path);
+      continue;
+    }
+    const manifest = env.path.join(pkg, 'browsers.json');
+    if (!(await env.exists(manifest))) {
+      // The project or its node_modules is gone; Playwright drops the link too.
+      continue;
+    }
+    try {
+      for (const dir of requiredDirs((await env.readText(manifest)) ?? '')) {
+        users.set(dir, [...(users.get(dir) ?? []), pkg]);
+      }
+    } catch {
+      unreadable.push(manifest);
+    }
+  }
+  return { users, unreadable };
+}
+
+/**
+ * Why `target`, a revision directory in a Playwright registry, must stay;
+ * null when no installed package needs it.
+ * @param {Map<string, Promise<object>>} [cache] registry → playwrightUsers
+ */
+export async function playwrightBlocker(env, target, cache = new Map()) {
+  const registry = env.path.dirname(target);
+  if (!cache.has(registry)) {
+    cache.set(registry, playwrightUsers(env, registry));
+  }
+  const { users, unreadable } = await cache.get(registry);
+  if (unreadable.length > 0) {
+    return `cannot read Playwright install record ${unreadable[0]}`;
+  }
+  const needed = users.get(env.path.basename(target));
+  return needed
+    ? `Playwright in ${needed[0]} still uses ${env.path.basename(target)}`
+    : null;
+}

package/src/report.js

@@ -82,7 +82,14 @@ function tierSection(report, tier, options) {
     '',
     `${tier.toUpperCase()}  ${plural(items.length, 'item')}, ${formatBytes(bytes)}`,
     ...limited(
-      items.map((item) => itemLine(item, showEnv)),
+      items.flatMap((item) => [
+        itemLine(item, showEnv),
+        ...(item.globalPackages?.length
+          ? [
+              `      also removes global packages: ${item.globalPackages.join(', ')}`,
+            ]
+          : []),
+      ]),
       options.limit
     ),
   ];
@@ -351,6 +358,23 @@ function timingLines(report, { verbose }) {
     });
 }
 
+function holderLine(holder) {
+  const details = [`${formatBytes(holder.memoryBytes)} memory`];
+  if (holder.compressedBytes !== undefined) {
+    details.push(`${formatBytes(holder.compressedBytes)} compressed`);
+  }
+  if (holder.swappedBytes !== undefined) {
+    details.push(`${formatBytes(holder.swappedBytes)} swapped`);
+  }
+  const change = holder.growth?.memoryBytes;
+  if (change) {
+    details.push(
+      `${change > 0 ? '+' : '-'}${formatBytes(Math.abs(change))} since ${new Date(holder.growth.since).toISOString()}`
+    );
+  }
+  return `${holder.pid} ${holder.command}: ${details.join(', ')}`;
+}
+
 /**
  * Renders a scan report.
  * @param {object} report
@@ -368,11 +392,12 @@ export function formatReport(report, options = {}) {
     lines.push(
       `Swap: ${formatBytes(host.swap.used)} used of ${formatBytes(host.swap.total)} (managed by macOS)`
     );
+    for (const warning of host.swap.warnings ?? []) {
+      lines.push(`WARNING: ${warning}`);
+    }
     lines.push(host.swap.attribution);
     for (const holder of host.swap.holders) {
-      lines.push(
-        `  ${holder.pid} ${holder.command}: ${formatBytes(holder.memoryBytes)} memory, ${formatBytes(holder.compressedBytes)} compressed`
-      );
+      lines.push(`  ${holderLine(holder)}`);
     }
     lines.push(host.swap.advice);
   }

package/src/rules/apps.js

@@ -36,13 +36,14 @@ export const APP_RULES = [
   },
   {
     id: 'telegram-downloaded-media',
-    excludeNames: ['cache', 'cache-storage', 'short-cache'],
     ecosystem: 'apps',
     tier: 'moderate',
     description:
       'Telegram downloaded media: secret-chat media may not be recoverable',
+    // Only media Telegram downloads again from its cloud; `storage` holds
+    // the media database and `local-file-*` files the user sent.
     paths: [
-      `${telegramAccounts}/*`,
+      `${telegramAccounts}/telegram-cloud-*`,
       ...telegramDesktop.map((root) => `${root}/user_data/downloads`),
     ],
     busy: ['Telegram', 'telegram-desktop'],

package/src/rules/downloads.js

@@ -20,10 +20,12 @@ export const DOWNLOAD_RULES = [
     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.
+    // `$TMPDIR` at launch and removes the clone when it exits. A clone
+    // stays while any process runs its hard-linked main executable (see
+    // ../scanners/app-clones.js): a browser name would block orphans
+    // forever, and open files miss a browser started before the update.
     paths: ['{TMP}/../X/*.code_sign_clone/code_sign_clone.*'],
+    appClone: { installed: ['/Applications', '~/Applications'] },
     directoryOnly: true,
     minAge: 'stale',
     busy: [],
@@ -31,13 +33,23 @@ export const DOWNLOAD_RULES = [
   {
     id: 'chrome-on-device-models',
     ecosystem: 'browsers',
-    description: 'superseded Chrome on-device AI model versions',
+    description:
+      'Chromium on-device AI models, downloaded again when a page uses built-in AI',
+    // Every installed version matches: the component updater fetches the
+    // model again on demand. A loaded model is held open and a download in
+    // progress writes to its directory, which the open-file check and the
+    // activity window catch.
     paths: [
-      '~/Library/Application Support/Google/Chrome/OptGuideOnDeviceModel/*',
-      '~/.config/google-chrome/OptGuideOnDeviceModel/*',
-      '{LOCALAPPDATA}/Google/Chrome/User Data/OptGuideOnDeviceModel/*',
-    ],
-    versionPattern: /^(?<version>\d+(?:\.\d+){1,3})$/,
+      '~/Library/Application Support/Google/Chrome*',
+      '~/Library/Application Support/Chromium',
+      '~/Library/Application Support/Microsoft Edge*',
+      '~/.config/google-chrome*',
+      '~/.config/chromium',
+      '{LOCALAPPDATA}/Google/Chrome*/User Data',
+      '{LOCALAPPDATA}/Chromium/User Data',
+      '{LOCALAPPDATA}/Microsoft/Edge*/User Data',
+    ].map((root) => `${root}/OptGuideOnDevice*Model/*`),
+    directoryOnly: true,
     minAge: 'stale',
     busy: [],
   },

package/src/rules/other.js

@@ -12,7 +12,11 @@
  * otherwise each match is its own item. `minAge: 'stale'` only reports
  * matches untouched for the stale-age window, `minAge: 'inactive'` for the
  * project inactivity window. `git: true` refuses matches that are Git work
- * trees with uncommitted, unpushed, or stashed changes.
+ * trees with uncommitted, unpushed, or stashed changes. `git: 'clone'`
+ * matches only Git work trees with an https or ssh remote, and refuses them
+ * unless every worktree is clean and the remote still advertises every
+ * local commit. `registry: 'playwright'` keeps revisions that a Playwright
+ * package recorded in the registry's `.links` still launches.
  */
 
 export const OTHER_RULES = [
@@ -29,15 +33,10 @@ export const OTHER_RULES = [
     versionPattern: /^(?<family>[a-z_]+)-(?<version>\d+)$/,
     minAge: 'inactive',
     tier: 'safe',
-    busy: [
-      'playwright',
-      'playwright-mcp',
-      'chrome',
-      'chromium',
-      'headless_shell',
-      'firefox',
-      'webkit',
-    ],
+    registry: 'playwright',
+    // A running Playwright launches the revisions its package names, which
+    // the registry check keeps; a revision a browser runs from is open.
+    busy: [],
   },
   {
     id: 'playwright-go-drivers',
@@ -519,6 +518,23 @@ export const OTHER_RULES = [
     minAge: 'stale',
     busy: ['chrome', 'chromium', 'headless_shell'],
   },
+  {
+    id: 'tmp-playwright-browsers',
+    ecosystem: 'tmp',
+    scope: 'tmp',
+    description:
+      'Playwright browser installs and downloads in temporary directories',
+    paths: [
+      '{TMP}/playwright-download-*',
+      '{TMP}/ms-playwright',
+      '{TMP}/ms-playwright-*',
+      '{TMP}/*/ms-playwright',
+      '{TMP}/*/.cache/ms-playwright',
+      '{TMP}/*/Library/Caches/ms-playwright',
+    ],
+    minAge: 'stale',
+    busy: ['playwright', 'node', 'chrome', 'chromium', 'headless_shell'],
+  },
   {
     id: 'node-tmp-caches',
     ecosystem: 'tmp',
@@ -533,3 +549,33 @@ export const OTHER_RULES = [
     busy: ['node'],
   },
 ];
+
+/**
+ * Checkouts cloned into temporary directories by tools, tests and agents,
+ * checked after every named rule so a more specific rule claims its own
+ * paths first.
+ */
+export const TEMP_CLONE_RULES = [
+  {
+    id: 'temp-git-clones',
+    ecosystem: 'tmp',
+    scope: 'tmp',
+    description:
+      'Git clones in temporary directories whose commits all exist on a remote',
+    tier: 'safe',
+    paths: ['{TMP}/*', '{TMP}/*/*'],
+    directoryOnly: true,
+    minAge: 'stale',
+    git: 'clone',
+    busy: [
+      'git',
+      'claude',
+      'codex',
+      'opencode',
+      'agent',
+      'node',
+      'bun',
+      'cargo',
+    ],
+  },
+];

package/src/rules/versions.js

@@ -10,6 +10,9 @@
  * 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.
+ * `locks` names the lock file a manager writes for each running process of
+ * a version (`{version}` is replaced); a lock naming a live process, or one
+ * that cannot be read, keeps the version.
  *
  * `versionOf(dirPath)` maps an install directory to the version string that
  * defaults and pin files are compared with (see `versionMatches`).
@@ -114,6 +117,7 @@ export const VERSION_RULES = [
     dirs: ['~/.local/share/claude/versions/*'],
     installTypes: ['file'],
     defaultLinks: ['~/.local/bin/claude'],
+    locks: '~/.local/state/claude/locks/{version}.lock',
     busy: ['claude'],
     recheck: true,
   },

package/src/scan.js

@@ -7,6 +7,7 @@ import {
   configureContainerHost,
   resetWritableLayers,
 } from './docker/writable.js';
+import path from 'node:path';
 import { setInterval, clearInterval } from 'node:timers';
 import { scanDocker } from './docker/scan.js';
 import { LocalEnv } from './env/local.js';
@@ -20,10 +21,11 @@ import { LivenessProbe } from './liveness.js';
 import { resolveOptions } from './options.js';
 import { existingPaths, isWithin, matchesExcluded } from './paths.js';
 import { scanAgents } from './scanners/agents.js';
-import { scanGlobal } from './scanners/global.js';
+import { GLOBAL_RULES, scanGlobal, targetedRules } from './scanners/global.js';
 import { scanProjects } from './scanners/projects.js';
 import { scanSystem } from './scanners/system.js';
 import { scanVersions } from './scanners/versions.js';
+import { VERSION_RULES } from './rules/versions.js';
 import { readSwap } from './swap.js';
 import {
   authenticateReport,
@@ -194,6 +196,17 @@ export async function environmentContext(env, options, overrides = {}) {
  * @param {{roots?: string[]|null, errors?: object[]}} [extra]
  * @returns {Promise<object[]>} items
  */
+/** A run limited to global or version rules skips the other scanners. */
+function selectedScanners(options) {
+  if (!targetedRules(options.only)) {
+    return options.scanners;
+  }
+  const rules = { global: GLOBAL_RULES, versions: VERSION_RULES };
+  return options.scanners.filter(
+    (name) => rules[name] && targetedRules(options.only, rules[name]).length > 0
+  );
+}
+
 export async function scanEnvironment(env, options, extra = {}) {
   const controller = new AbortController();
   const abort = () => controller.abort(options.signal.reason);
@@ -321,7 +334,7 @@ async function scanEnvironmentScoped(
   };
   context.ready = ready;
   let incomplete = false;
-  for (const name of options.scanners) {
+  for (const name of selectedScanners(options)) {
     checkSignal(env.signal);
     context.scanner = name;
     stage(name);
@@ -434,12 +447,33 @@ export async function selfContainerIds(env) {
   return [...ids];
 }
 
-function matchesOnly(item, only) {
+/**
+ * `only` entries name an ecosystem, rule, kind or item id, or a path or
+ * glob: an item matches it when each of its paths lies inside the path, or
+ * the path or one of its ancestors matches the glob.
+ */
+function matchesOnly(item, only, pathApi = path) {
   return (
     only.length === 0 ||
     only.some(
       (entry) =>
-        entry === item.ecosystem || entry === item.rule || entry === item.kind
+        [item.ecosystem, item.rule, item.kind, item.id].includes(entry) ||
+        insideOnlyPath(item, entry, pathApi)
+    )
+  );
+}
+
+function insideOnlyPath(item, entry, pathApi) {
+  const glob = /[*?[]/.test(entry);
+  if (!glob && !pathApi.isAbsolute(entry) && !path.win32.isAbsolute(entry)) {
+    return false;
+  }
+  return (
+    item.paths?.length > 0 &&
+    item.paths.every((target) =>
+      glob
+        ? matchesExcluded(target, [entry], pathApi)
+        : isWithin(target, entry, pathApi)
     )
   );
 }
@@ -476,7 +510,7 @@ export function filterItems(items, options, daemons = [], pathApi) {
         item.sizeUnknown ||
         item.imageBytes >= options.minSizeBytes ||
         item.container?.pinnedImage?.bytes >= options.minSizeBytes) &&
-      matchesOnly(item, options.only) &&
+      matchesOnly(item, options.only, pathApi) &&
       !excluded(item, options.exclude, pathApi) &&
       !underDaemonRoot(item, daemons, pathApi)
   );
@@ -496,13 +530,17 @@ function envDescriptor(env, depth, chain) {
   };
 }
 
-async function withDisk(env, descriptor) {
+async function withDisk(env, descriptor, options) {
   const target = env.platform === 'win32' ? env.currentHome : '/';
   const disk = await env.diskUsage(target).catch(() => null);
   return {
     ...descriptor,
     disk: disk ? { path: target, ...disk } : null,
-    swap: await readSwap(env),
+    swap: await readSwap(env, {
+      stateDir: options.cacheDir,
+      disk,
+      now: options.now?.(),
+    }),
   };
 }
 
@@ -632,7 +670,7 @@ async function scanScoped(input) {
     environments.push(inner);
   }
   environments[0] = await timed(env.timings, 'disk', () =>
-    withDisk(env, environments[0])
+    withDisk(env, environments[0], options)
   );
   environments[0].timings = env.timings.toJSON();
   const report = buildReport({

package/src/scanners/app-clones.js

@@ -0,0 +1,53 @@
+/**
+ * Chromium browsers on macOS clone their app bundle at launch with APFS
+ * `clonefile` and replace the clone's main executable with a hard link to
+ * the installed one (chrome/browser/mac/code_sign_clone_manager.mm). The
+ * browser holds no file open inside its clone: it runs the shared inode,
+ * which `lsof` reports under the installed path until an update replaces
+ * the app. After an update the clone keeps the running browser's code
+ * signature valid, so a clone stays while any process runs its executable.
+ * Until then the clone shares every block with the installed app, and
+ * removing it frees nothing but directory entries.
+ */
+
+const BUNDLE_SUFFIX = '.bundle';
+
+/**
+ * Main executables of the bundle cloned in `clone`, and whether the clone
+ * still shares its blocks with an app installed in one of `appDirs`.
+ * @returns {Promise<{executables: string[], sharedWith: string|null}>}
+ */
+export async function appCloneDetails(env, clone, appDirs) {
+  const executables = [];
+  let sharedWith = null;
+  for (const bundle of await env.list(clone)) {
+    if (
+      bundle.type !== 'dir' ||
+      !bundle.name.endsWith(`.app${BUNDLE_SUFFIX}`)
+    ) {
+      continue;
+    }
+    const appName = bundle.name.slice(0, -BUNDLE_SUFFIX.length);
+    const macos = env.path.join(bundle.path, 'Contents', 'MacOS');
+    for (const entry of await env.list(macos)) {
+      if (entry.type !== 'file') {
+        continue;
+      }
+      executables.push(entry.path);
+      sharedWith ??= await installedCopy(env, entry, appName, appDirs);
+    }
+  }
+  return { executables, sharedWith };
+}
+
+async function installedCopy(env, executable, appName, appDirs) {
+  const inode = (await env.stat(executable.path))?.inode;
+  for (const dir of appDirs) {
+    const app = env.path.join(dir, appName);
+    const installed = env.path.join(app, 'Contents', 'MacOS', executable.name);
+    if (inode && (await env.stat(installed))?.inode === inode) {
+      return app;
+    }
+  }
+  return null;
+}

package/src/scanners/common.js

@@ -27,6 +27,7 @@ export async function listMany(env, dirs) {
  */
 export async function scanTimeBusy(context, item) {
   await resolvePaths(context, item.paths);
+  await context.liveness?.resolveExecutables(item.checks?.executables);
   return context.liveness ? context.liveness.busyReason(item) : null;
 }