disk-space-saviour 0.20.0 → 0.21.0

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: [],

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/scan.js

@@ -530,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?.(),
+    }),
   };
 }
 
@@ -666,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;
 }
 

package/src/scanners/global.js

@@ -1,4 +1,4 @@
-import { scanItems } from '../env/scope.js';
+import { checkSignal, scanItems } from '../env/scope.js';
 /**
  * Global per-user caches (ecosystem download and compilation caches, IDE and
  * browser caches), system package caches, and leftovers in temporary
@@ -7,7 +7,7 @@ import { scanItems } from '../env/scope.js';
  */
 
 import { CACHE_RULES } from '../rules/ecosystems.js';
-import { OTHER_RULES } from '../rules/other.js';
+import { OTHER_RULES, TEMP_CLONE_RULES } from '../rules/other.js';
 import { APP_RULES, expandChromiumCaches } from '../rules/apps.js';
 import { VERSION_RULES, compareVersions } from '../rules/versions.js';
 import { block, makeItem } from '../items.js';
@@ -17,6 +17,10 @@ import { configuredPattern } from '../env/cache-roots.js';
 import { TOOLCHAIN_CACHE_RULES } from '../rules/toolchains.js';
 import { DOWNLOAD_RULES } from '../rules/downloads.js';
 import { timed } from '../timings.js';
+import { appCloneDetails } from './app-clones.js';
+import { gitDirectories } from '../git.js';
+import { networkRemotes } from '../git-remote.js';
+import { playwrightBlocker } from '../playwright-registry.js';
 
 export const GLOBAL_RULES = [
   ...CACHE_RULES,
@@ -24,6 +28,7 @@ export const GLOBAL_RULES = [
   ...APP_RULES,
   ...TOOLCHAIN_CACHE_RULES,
   ...DOWNLOAD_RULES,
+  ...TEMP_CLONE_RULES,
 ];
 
 function scopeBases(rule, homes, tmpDirs) {
@@ -173,7 +178,13 @@ function olderVersions(env, rule, paths, stats) {
   return paths.filter((target) => old.has(target));
 }
 
-async function buildItem(context, rule, base, group) {
+/** What cleanup re-verifies right before deleting, by the rule's `git` mode. */
+const GIT_RECHECKS = {
+  ifPresent: { type: 'scratch' },
+  clone: { type: 'clone' },
+};
+
+async function buildItem(context, rule, base, group, homes) {
   const { env } = context;
   const paths = group.map((entry) => entry.path);
   const appRoot = rule.markers
@@ -195,7 +206,7 @@ async function buildItem(context, rule, base, group) {
     reason: rule.minAge
       ? `untouched for longer than the ${rule.minAge === 'stale' ? 'activity' : 'inactivity'} window`
       : 're-downloaded or re-created on demand',
-    recheck: rule.git === 'ifPresent' ? { type: 'scratch' } : undefined,
+    recheck: GIT_RECHECKS[rule.git],
     action: action ?? { type: 'none' },
     checks: {
       busy: [
@@ -207,10 +218,31 @@ async function buildItem(context, rule, base, group) {
     },
   });
   block(item, blocker);
+  if (rule.appClone) {
+    await describeAppClone(context, rule, item, homes);
+  }
   await addBlockers(context, rule, item);
   return item;
 }
 
+async function describeAppClone(context, rule, item, homes) {
+  const { env } = context;
+  const appDirs = rule.appClone.installed
+    .flatMap((dir) =>
+      homes.map((home) => expandRulePath(dir, { home, pathApi: env.path }))
+    )
+    .filter(Boolean);
+  const { executables, sharedWith } = await appCloneDetails(env, item.path, [
+    ...new Set(appDirs),
+  ]);
+  item.checks.executables = executables;
+  if (sharedWith) {
+    // Every block is shared with the installed app: nothing to reclaim.
+    item.bytes = 0;
+    item.reason = `shares its disk blocks with ${sharedWith}`;
+  }
+}
+
 async function addBlockers(context, rule, item) {
   const { env, git } = context;
   if (rule.scope === 'system' && !(await env.isRoot())) {
@@ -218,13 +250,24 @@ async function addBlockers(context, rule, item) {
   }
   if (rule.git) {
     for (const target of item.paths) {
-      for (const reason of await git.treeBlockers(target, {
-        allowNoRepo: rule.git === 'ifPresent',
-      })) {
+      for (const reason of rule.git === 'clone'
+        ? await git.cloneBlockers(target)
+        : await git.treeBlockers(target, {
+            allowNoRepo: rule.git === 'ifPresent',
+          })) {
         block(item, reason);
       }
     }
   }
+  if (rule.registry === 'playwright') {
+    context.playwrightRegistries ??= new Map();
+    for (const target of item.paths) {
+      block(
+        item,
+        await playwrightBlocker(env, target, context.playwrightRegistries)
+      );
+    }
+  }
   const busy = await scanTimeBusy(context, item);
   if (busy) {
     block(item, `busy: ${busy}`);
@@ -292,9 +335,12 @@ export async function scanGlobal(
 
     const accepted = [];
     for (const target of candidates) {
+      // Acceptance can read Git metadata of thousands of temporary entries
+      // without passing through the environment, so honour the budget here.
+      checkSignal(env.signal);
       if (
         !(await timed(context.timings, 'global:accept', () =>
-          acceptedPath(env, rule, target, stats)
+          acceptedPath(env, rule, target, stats, seen)
         ))
       ) {
         continue;
@@ -338,7 +384,7 @@ export async function scanGlobal(
       : measured.filter(large).map((entry) => [entry]);
     for (const group of groups.filter((g) => g.length > 0)) {
       const item = await timed(context.timings, 'global:item', () =>
-        buildItem(context, rule, base, group)
+        buildItem(context, rule, base, group, homes)
       );
       items.push(item);
       if ((await context.ready?.([item])) === false) {
@@ -349,7 +395,40 @@ export async function scanGlobal(
   return items;
 }
 
-async function acceptedPath(env, rule, target, stats) {
+/**
+ * Whether `target` or one of its ancestors is in `claimed`. Both come from
+ * the same glob expansion, so ancestors compare as plain strings and the
+ * cost is the path depth, not the number of claimed paths.
+ */
+function claimedAbove(env, target, claimed) {
+  for (let dir = target; ; dir = env.path.dirname(dir)) {
+    if (claimed.has(dir)) {
+      return true;
+    }
+    if (env.path.dirname(dir) === dir) {
+      return false;
+    }
+  }
+}
+
+/**
+ * A temporary directory holding a Git work tree with a network remote,
+ * outside every path another rule (or a parent clone) already claimed.
+ */
+async function tempClone(env, target, seen) {
+  if (env.kind !== 'host' || claimedAbove(env, target, seen)) {
+    return false;
+  }
+  try {
+    // Other users' temporary directories are unreadable; that is no error.
+    const { commonDir } = await gitDirectories(target);
+    return (await networkRemotes(commonDir)).length > 0;
+  } catch {
+    return false;
+  }
+}
+
+async function acceptedPath(env, rule, target, stats, seen = new Set()) {
   const name = env.path.basename(target);
   if (rule.excludeNames?.includes(name)) {
     return false;
@@ -357,6 +436,9 @@ async function acceptedPath(env, rule, target, stats) {
   if (rule.directoryOnly && stats.get(target)?.type !== 'dir') {
     return false;
   }
+  if (rule.git === 'clone' && !(await tempClone(env, target, seen))) {
+    return false;
+  }
   if (rule.fileOnly && stats.get(target)?.type !== 'file') {
     return false;
   }

package/src/scanners/versions.js

@@ -235,11 +235,13 @@ function referencedInstalls(rule, installs, refs, versionOf) {
 }
 
 /**
- * Global packages a user installed into a version (`npm install -g`) are
- * lost with it. Packages bundled with the runtime and caches that are
- * installed again on demand (`rule.globalPackages.regenerable`) are not.
+ * Global packages a user installed into a version (`npm install -g`) go
+ * with it, so the item names them. Packages bundled with the runtime and
+ * caches installed again on demand (`rule.globalPackages.regenerable`) are
+ * not named. A package that is running keeps the version through the
+ * process checks: its binary, arguments or PATH entry lies inside.
  */
-async function blockGlobalPackages(env, rule, dir, item) {
+async function noteGlobalPackages(env, rule, dir, item) {
   if (!rule.globalPackages) {
     return;
   }
@@ -262,7 +264,8 @@ async function blockGlobalPackages(env, rule, dir, item) {
   if (own.length > 0) {
     const shown = own.slice(0, 5).join(', ');
     const more = own.length > 5 ? ` and ${own.length - 5} more` : '';
-    block(item, `has globally installed packages: ${shown}${more}`);
+    item.globalPackages = own;
+    item.reason += `; also removes its global packages: ${shown}${more}`;
   }
 }
 
@@ -357,7 +360,7 @@ async function ruleItems(context, rule, home, pins) {
           : null,
     });
     await blockPyenvEnvironments(env, rule, dir, item);
-    await blockGlobalPackages(env, rule, dir, item);
+    await noteGlobalPackages(env, rule, dir, item);
     await blockLiveLock(context, rule, home, version, item);
     const busy = await scanTimeBusy(context, item);
     if (busy) {