disk-space-saviour 0.19.0 → 0.21.0

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,9 +7,9 @@ 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 { compareVersions } from '../rules/versions.js';
+import { VERSION_RULES, compareVersions } from '../rules/versions.js';
 import { block, makeItem } from '../items.js';
 import { expandGlobPaths, expandRulePath, isWithin } from '../paths.js';
 import { olderThan, scanTimeBusy, resolvePaths } from './common.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,24 +250,56 @@ 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}`);
   }
 }
 
+const namesRule = (entry, rule) =>
+  entry === rule.id || entry.includes(`:${rule.id}:`);
+
+/**
+ * Rules of `rules` that `only` entries name directly or through an item id
+ * (`env:rule:path`), when every entry names a global or version rule; null
+ * when an entry may match anything else and every rule has to run.
+ */
+export function targetedRules(only = [], rules = GLOBAL_RULES) {
+  const targetable = [...GLOBAL_RULES, ...VERSION_RULES];
+  const covered =
+    only.length > 0 &&
+    only.every((entry) => targetable.some((rule) => namesRule(entry, rule)));
+  return covered
+    ? rules.filter((rule) => only.some((entry) => namesRule(entry, rule)))
+    : null;
+}
+
 /**
  * Scans global cache and leftover locations.
  * @returns {Promise<object[]>} report items
  */
-export async function scanGlobal(context, { rules = GLOBAL_RULES } = {}) {
+export async function scanGlobal(
+  context,
+  { rules = targetedRules(context.options.only) ?? GLOBAL_RULES } = {}
+) {
   const { env, options } = context;
   const homes = options.homes ?? (await env.homeDirs());
   const tmpDirs = options.tmpDirs ?? (await env.tmpDirs());
@@ -271,9 +335,12 @@ export async function scanGlobal(context, { rules = GLOBAL_RULES } = {}) {
 
     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;
@@ -317,7 +384,7 @@ export async function scanGlobal(context, { rules = GLOBAL_RULES } = {}) {
       : 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) {
@@ -328,7 +395,40 @@ export async function scanGlobal(context, { rules = GLOBAL_RULES } = {}) {
   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;
@@ -336,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

@@ -20,6 +20,7 @@ import { block, makeItem } from '../items.js';
 import { expandGlobPath, expandRulePath } from '../paths.js';
 import { scanTimeBusy, resolvePaths } from './common.js';
 import { configuredPattern } from '../env/cache-roots.js';
+import { targetedRules } from './global.js';
 
 async function installDirs(env, rule, home) {
   const dirs = [];
@@ -234,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;
   }
@@ -261,7 +264,44 @@ 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}`;
+  }
+}
+
+/**
+ * Lock files a manager writes for every running process of a version
+ * (`rule.locks`, `{version}` replaced). A version stays while its lock names
+ * a live process, and while the lock or the process list cannot be read.
+ */
+async function blockLiveLock(context, rule, home, version, item) {
+  if (!rule.locks) {
+    return;
+  }
+  const { env } = context;
+  const file = expandRulePath(rule.locks.replace('{version}', version), {
+    home,
+    pathApi: env.path,
+  });
+  if (!(await env.exists(file))) {
+    return;
+  }
+  let pid = null;
+  try {
+    pid = JSON.parse((await env.readText(file)) ?? '').pid;
+  } catch {
+    pid = null;
+  }
+  if (!Number.isInteger(pid) || pid <= 0) {
+    block(item, `${rule.manager} lock ${file} cannot be read`);
+    return;
+  }
+  context.lockProcesses ??= env.processes().catch(() => null);
+  const processes = await context.lockProcesses;
+  if (!processes) {
+    block(item, `cannot verify the process holding ${file}`);
+  } else if (processes.some((proc) => proc.pid === pid)) {
+    block(item, `locked by running ${rule.manager} (pid ${pid}, ${file})`);
   }
 }
 
@@ -320,7 +360,8 @@ 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) {
       block(item, `busy: ${busy}`);
@@ -334,7 +375,12 @@ async function ruleItems(context, rule, home, pins) {
  * Scans version manager installs.
  * @returns {Promise<object[]>} report items
  */
-export async function scanVersions(context, { rules = VERSION_RULES } = {}) {
+export async function scanVersions(
+  context,
+  {
+    rules = targetedRules(context.options.only, VERSION_RULES) ?? VERSION_RULES,
+  } = {}
+) {
   const { env, options } = context;
   const homes = options.homes ?? (await env.homeDirs());
   const pins = await projectPins(

package/src/swap.js

@@ -1,5 +1,23 @@
-/** Swap is a capacity diagnostic, never a deletion candidate. */
-import { parseSize } from './units.js';
+/**
+ * Swap is a capacity diagnostic, never a deletion candidate. Swap files
+ * live on the system disk, so memory a process keeps but never touches
+ * turns into used disk space. Each scan records swap usage and the largest
+ * memory holders in the state directory; the next scan reports how much
+ * both grew since the oldest sample of the last week.
+ */
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { AGENT_NAMES } from './health.js';
+import { formatBytes, parseSize } from './units.js';
+
+const GIB = 1024 ** 3;
+export const HISTORY_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+const HISTORY_LIMIT = 200;
+const HOLDER_LIMIT = 10;
+/** Growth below this is noise from normal paging. */
+const GROWTH_WARNING_BYTES = GIB;
+/** A single process holding this much is worth naming in a warning. */
+const LARGE_HOLDER_BYTES = 2 * GIB;
 
 export function parseSwapUsage(text) {
   const match =
@@ -31,39 +49,279 @@ export function parseMemoryHolders(text) {
       compressedBytes: parseSize(match[4].replace(/[+-]$/, '')),
     }))
     .sort((a, b) => b.memoryBytes - a.memoryBytes)
-    .slice(0, 10);
+    .slice(0, HOLDER_LIMIT);
+}
+
+/** Swap totals from `/proc/meminfo`, or null. */
+export function parseMeminfo(text) {
+  const field = (name) => {
+    const match = new RegExp(`^${name}:\\s+(\\d+)\\s*kB`, 'm').exec(text);
+    return match ? Number(match[1]) * 1024 : null;
+  };
+  const total = field('SwapTotal');
+  const free = field('SwapFree');
+  return total === null || free === null || total === 0
+    ? null
+    : { total, used: total - free, free };
+}
+
+/** Name, PID, resident and swapped bytes from a `/proc/<pid>/status`. */
+export function parseProcStatus(text) {
+  const value = (name) => new RegExp(`^${name}:\\s+(.*)$`, 'm').exec(text)?.[1];
+  const kib = (name) => Number(/^(\d+)/.exec(value(name) ?? '')?.[1] ?? 0);
+  const pid = Number(value('Pid'));
+  if (!Number.isInteger(pid)) {
+    return null;
+  }
+  const residentBytes = kib('VmRSS') * 1024;
+  const swappedBytes = kib('VmSwap') * 1024;
+  return {
+    pid,
+    command: value('Name')?.trim() ?? '',
+    memoryBytes: residentBytes + swappedBytes,
+    swappedBytes,
+  };
+}
+
+async function linuxHolders(procRoot) {
+  const pids = (await fsp.readdir(procRoot)).filter((name) =>
+    /^\d+$/.test(name)
+  );
+  const holders = await Promise.all(
+    pids.map((pid) =>
+      fsp
+        .readFile(path.join(procRoot, pid, 'status'), 'utf8')
+        .then(parseProcStatus, () => null)
+    )
+  );
+  return holders
+    .filter((holder) => holder && holder.memoryBytes > 0)
+    .sort(
+      (a, b) => b.swappedBytes - a.swappedBytes || b.memoryBytes - a.memoryBytes
+    )
+    .slice(0, HOLDER_LIMIT);
+}
+
+async function readDarwin(env) {
+  const usage = await env.run(['sysctl', 'vm.swapusage']);
+  const swap = usage.code === 0 ? parseSwapUsage(usage.stdout) : null;
+  if (!swap) {
+    return null;
+  }
+  const top = await env.run([
+    'top',
+    '-l',
+    '1',
+    '-o',
+    'mem',
+    '-n',
+    String(HOLDER_LIMIT),
+    '-stats',
+    'pid,command,mem,cmprs',
+  ]);
+  return {
+    ...swap,
+    holders: top.code === 0 ? parseMemoryHolders(top.stdout) : [],
+    attribution:
+      'Largest memory consumers (memory includes compressed and swapped pages); macOS does not expose per-process swap ownership here.',
+    advice:
+      'If Docker Desktop is consuming memory, restart it after saving running work or lower its VM memory limit. Swap files are managed by macOS; dss never deletes them.',
+  };
 }
 
-export async function readSwap(env) {
-  if (env.kind !== 'host' || env.platform !== 'darwin') {
+async function readLinux(procRoot) {
+  const swap = parseMeminfo(
+    await fsp.readFile(path.join(procRoot, 'meminfo'), 'utf8')
+  );
+  if (!swap) {
     return null;
   }
+  return {
+    ...swap,
+    holders: await linuxHolders(procRoot),
+    attribution:
+      'Processes with the most swapped memory (VmSwap in /proc/<pid>/status), then the most resident memory.',
+    advice:
+      'Swap is managed by the kernel; dss never deletes swap files or partitions.',
+  };
+}
+
+const holderKey = (holder) => `${holder.pid}\0${holder.command}`;
+
+/** Samples of the last week, oldest first; missing state is empty. */
+export async function loadSwapHistory(stateDir, now) {
+  if (!stateDir) {
+    return [];
+  }
+  try {
+    const data = JSON.parse(
+      await fsp.readFile(path.join(stateDir, 'swap-history.json'), 'utf8')
+    );
+    return (Array.isArray(data.samples) ? data.samples : []).filter(
+      (sample) =>
+        Number.isFinite(sample?.time) &&
+        sample.time <= now &&
+        now - sample.time <= HISTORY_WINDOW_MS
+    );
+  } catch {
+    return [];
+  }
+}
+
+async function saveSwapHistory(stateDir, samples) {
+  if (!stateDir) {
+    return;
+  }
   try {
-    const usage = await env.run(['sysctl', 'vm.swapusage']);
-    const swap = usage.code === 0 ? parseSwapUsage(usage.stdout) : null;
-    if (!swap) {
-      return null;
+    await fsp.mkdir(stateDir, { recursive: true, mode: 0o700 });
+    const file = path.join(stateDir, 'swap-history.json');
+    const temporary = `${file}.${process.pid}`;
+    await fsp.writeFile(
+      temporary,
+      JSON.stringify({ schema: 1, samples: samples.slice(-HISTORY_LIMIT) }),
+      { mode: 0o600 }
+    );
+    await fsp.rename(temporary, file);
+  } catch {
+    // History only adds growth figures; a read-only state dir loses them.
+  }
+}
+
+/**
+ * Adds swap and per-holder growth since the oldest sample of `history`.
+ * A holder's baseline is the oldest sample that lists the same PID and
+ * command, so a restarted process starts over.
+ */
+export function withGrowth(swap, history) {
+  const baseline = history[0];
+  const firstSeen = new Map();
+  for (const sample of history) {
+    for (const holder of sample.holders ?? []) {
+      if (!firstSeen.has(holderKey(holder))) {
+        firstSeen.set(holderKey(holder), { time: sample.time, ...holder });
+      }
+    }
+  }
+  return {
+    ...swap,
+    growth: baseline
+      ? { since: baseline.time, usedBytes: swap.used - baseline.used }
+      : null,
+    holders: swap.holders.map((holder) => {
+      const first = firstSeen.get(holderKey(holder));
+      return first
+        ? {
+            ...holder,
+            growth: {
+              since: first.time,
+              memoryBytes: holder.memoryBytes - first.memoryBytes,
+            },
+          }
+        : holder;
+    }),
+  };
+}
+
+const isAgent = (holder) =>
+  AGENT_NAMES.includes(holder.command.trim().toLowerCase());
+
+function holderSummary(holder) {
+  const grew =
+    holder.growth?.memoryBytes > 0
+      ? `, +${formatBytes(holder.growth.memoryBytes)} since ${new Date(holder.growth.since).toISOString()}`
+      : '';
+  return `${holder.command} (pid ${holder.pid}): ${formatBytes(holder.memoryBytes)}${grew}`;
+}
+
+/**
+ * Warnings for swap that is large, growing, or larger than the free disk
+ * space it can grow into, naming the processes that hold the memory.
+ * @param {object} swap result of `withGrowth`
+ * @param {{free: number}|null} disk
+ * @returns {string[]}
+ */
+export function swapWarnings(swap, disk) {
+  const reasons = [];
+  if (swap.growth && swap.growth.usedBytes >= GROWTH_WARNING_BYTES) {
+    reasons.push(
+      `grew by ${formatBytes(swap.growth.usedBytes)} since ${new Date(swap.growth.since).toISOString()}`
+    );
+  }
+  if (swap.total > 0 && swap.used >= GIB && swap.used >= 0.75 * swap.total) {
+    reasons.push(
+      `is ${Math.round((100 * swap.used) / swap.total)}% full, so the system adds swap files on disk when memory demand grows`
+    );
+  }
+  if (disk && swap.used >= GIB && disk.free < swap.used) {
+    reasons.push(
+      `has only ${formatBytes(disk.free)} of free disk to grow into, less than the ${formatBytes(swap.used)} already used`
+    );
+  }
+  if (reasons.length === 0) {
+    return [];
+  }
+  // The kernel (PID 0) cannot be quit, so naming it helps nobody.
+  const candidates = swap.holders.filter((holder) => holder.pid > 0);
+  const growing = candidates.filter(
+    (holder) => holder.growth?.memoryBytes >= GROWTH_WARNING_BYTES
+  );
+  const large = candidates.filter(
+    (holder) => holder.memoryBytes >= LARGE_HOLDER_BYTES
+  );
+  const named = [...new Set([...growing, ...large])].slice(0, 5);
+  const warnings = [`Swap ${reasons.join('; ')}.`];
+  if (named.length > 0) {
+    warnings.push(
+      `Memory held by: ${named.map(holderSummary).join('; ')}. Quitting or restarting them frees that swap and its disk space.`
+    );
+  }
+  if (named.some(isAgent)) {
+    warnings.push(
+      'Long-running AI agent sessions keep their history in memory: quit the session and resume it (for example `codex resume <session-id>` or `claude --resume`) to release it without losing the conversation.'
+    );
+  }
+  return warnings;
+}
+
+/**
+ * Swap usage, its largest memory holders, growth since earlier scans and
+ * warnings; null where swap cannot be read.
+ * @param {object} env
+ * @param {{stateDir?: string|false, disk?: object|null, now?: number,
+ *   procRoot?: string}} [options]
+ */
+export async function readSwap(env, options = {}) {
+  if (env.kind !== 'host') {
+    return null;
+  }
+  const { stateDir, disk = null, now = Date.now() } = options;
+  let swap = null;
+  try {
+    if (env.platform === 'darwin') {
+      swap = await readDarwin(env);
+    } else if (env.platform === 'linux') {
+      swap = await readLinux(options.procRoot ?? '/proc');
     }
-    const top = await env.run([
-      'top',
-      '-l',
-      '1',
-      '-o',
-      'mem',
-      '-n',
-      '10',
-      '-stats',
-      'pid,command,mem,cmprs',
-    ]);
-    return {
-      ...swap,
-      holders: top.code === 0 ? parseMemoryHolders(top.stdout) : [],
-      attribution:
-        'Largest resident/compressed memory consumers; macOS does not expose per-process swap ownership here.',
-      advice:
-        'If Docker Desktop is consuming memory, restart it after saving running work or lower its VM memory limit. Swap files are managed by macOS; dss never deletes them.',
-    };
   } catch {
+    swap = null;
+  }
+  if (!swap) {
     return null;
   }
+  const history = await loadSwapHistory(stateDir, now);
+  const grown = withGrowth(swap, history);
+  await saveSwapHistory(stateDir, [
+    ...history,
+    {
+      time: now,
+      used: swap.used,
+      total: swap.total,
+      holders: swap.holders.map(({ pid, command, memoryBytes }) => ({
+        pid,
+        command,
+        memoryBytes,
+      })),
+    },
+  ]);
+  return { ...grown, warnings: swapWarnings(grown, disk) };
 }