disk-space-saviour 0.21.0 → 0.22.1

package/src/report.js

@@ -114,6 +114,72 @@ function blockedSection(report, options) {
   ];
 }
 
+/**
+ * Clones that share every block with an installed app: `du` and Finder
+ * count them at full size, deleting them frees nothing.
+ */
+export function sharedSection(shared) {
+  if (!shared?.length) {
+    return [];
+  }
+  const apparent = shared.reduce((sum, item) => sum + item.apparentBytes, 0);
+  return [
+    '',
+    `SHARED WITH INSTALLED APPS  ${plural(shared.length, 'item')}, ${formatBytes(apparent)} as du counts it, about 0 B to free (APFS clones; the app recreates them at launch)`,
+    ...shared.map(
+      (item) =>
+        `  ${pad(formatBytes(item.apparentBytes), 10)}  ${item.rule}  ${item.path}  (shares its blocks with ${item.sharedWith})`
+    ),
+  ];
+}
+
+function tierBreakdown(tiers) {
+  return TIERS.filter((tier) => tiers[tier])
+    .map((tier) => `${tier} ${formatBytes(tiers[tier])}`)
+    .join(', ');
+}
+
+/** One-line warning naming the largest conditions, or null. */
+export function conditionsWarning(blocked) {
+  const conditions = blocked?.conditions ?? [];
+  if (conditions.length === 0) {
+    return null;
+  }
+  const bytes = conditions.reduce((sum, group) => sum + group.bytes, 0);
+  const top = conditions
+    .slice(0, 3)
+    .map((group) => `${group.action} (${formatBytes(group.bytes)})`);
+  const more = conditions.length > 3 ? `, ${conditions.length - 3} more` : '';
+  return `${formatBytes(bytes)} more frees only once something stops using it: ${top.join('; ')}${more}. See FREEABLE ON CONDITIONS.`;
+}
+
+function conditionsWarningLines(blocked) {
+  const warning = conditionsWarning(blocked);
+  return warning ? [`WARNING: ${warning}`] : [];
+}
+
+/** Blocked space grouped by the condition that frees it. */
+export function conditionsSection(blocked, options = {}) {
+  const conditions = blocked?.conditions ?? [];
+  if (conditions.length === 0) {
+    return [];
+  }
+  const lines = conditions.map(
+    (group) =>
+      `  ${pad(formatBytes(group.bytes), 9)}  ${group.action} (${plural(group.items, 'item')}: ${tierBreakdown(group.tiers)})`
+  );
+  if (blocked.other?.items) {
+    lines.push(
+      `  ${pad(formatBytes(blocked.other.bytes), 9)}  kept for other reasons (Git state, still needed, protected or unverifiable): ${plural(blocked.other.items, 'item')}`
+    );
+  }
+  return [
+    '',
+    'FREEABLE ON CONDITIONS (blocked items free once these happen; rerun dss afterwards)',
+    ...limited(lines, options.limit ?? DEFAULT_LIMIT),
+  ];
+}
+
 function repoSummary(repo) {
   if (repo.error) {
     return `${repo.root}: ${repo.error}`;
@@ -372,7 +438,39 @@ function holderLine(holder) {
       `${change > 0 ? '+' : '-'}${formatBytes(Math.abs(change))} since ${new Date(holder.growth.since).toISOString()}`
     );
   }
-  return `${holder.pid} ${holder.command}: ${details.join(', ')}`;
+  const self = holder.self ? ' (this dss run)' : '';
+  return `${holder.pid} ${holder.command}${self}: ${details.join(', ')}`;
+}
+
+function swapLines(swap) {
+  if (!swap) {
+    return [];
+  }
+  return [
+    `Swap: ${formatBytes(swap.used)} used of ${formatBytes(swap.total)} (managed by macOS)`,
+    ...(swap.warnings ?? []).map((warning) => `WARNING: ${warning}`),
+    swap.attribution,
+    ...swap.holders.map((holder) => `  ${holderLine(holder)}`),
+    swap.advice,
+  ];
+}
+
+function environmentStatusLines(env) {
+  const lines = [];
+  if (env.layerSource) {
+    lines.push(`  ${env.label}: layer source ${env.layerSource}`);
+  }
+  if (env.scanStatus === 'goal-reached') {
+    lines.push(
+      `  ${env.label}: scan stopped after the free-space goal was met`
+    );
+  } else if (env.scanStatus && env.scanStatus !== 'complete') {
+    lines.push(`  ${env.label}: scan incomplete (${env.scanStatus})`);
+  }
+  if (env.hint) {
+    lines.push(`  ${env.label}: ${env.hint}`);
+  }
+  return lines;
 }
 
 /**
@@ -388,38 +486,15 @@ export function formatReport(report, options = {}) {
     `disk-space-saviour scan of ${host.label} in ${(report.durationMs / 1000).toFixed(1)}s (report only, nothing was deleted)`,
     formatDisk(host.disk),
   ];
-  if (host.swap) {
-    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(`  ${holderLine(holder)}`);
-    }
-    lines.push(host.swap.advice);
-  }
+  lines.push(...swapLines(host.swap));
+  lines.push(...conditionsWarningLines(report.totals?.blocked));
   for (const tier of TIERS) {
     lines.push(...tierSection(report, tier, { limit }));
   }
-  for (const env of report.environments) {
-    if (env.layerSource) {
-      lines.push(`  ${env.label}: layer source ${env.layerSource}`);
-    }
-    if (env.scanStatus === 'goal-reached') {
-      lines.push(
-        `  ${env.label}: scan stopped after the free-space goal was met`
-      );
-    } else if (env.scanStatus && env.scanStatus !== 'complete') {
-      lines.push(`  ${env.label}: scan incomplete (${env.scanStatus})`);
-    }
-    if (env.hint) {
-      lines.push(`  ${env.label}: ${env.hint}`);
-    }
-  }
+  lines.push(...report.environments.flatMap(environmentStatusLines));
   lines.push(...blockedSection(report, { limit }));
+  lines.push(...sharedSection(report.shared));
+  lines.push(...conditionsSection(report.totals?.blocked, { limit }));
   lines.push(...dockerSection(report));
   lines.push(...errorsSection(report.errors));
   lines.push(...totalsSection(report));
@@ -499,6 +574,14 @@ function emergencyLines(audit) {
  * @param {object} audit
  * @param {{verbose?: boolean}} [options]
  */
+/** Warns that a plan built on an incomplete scan misses what it never reached. */
+export function incompleteScanLines(incomplete) {
+  return (incomplete ?? []).map(
+    (env) =>
+      `WARNING: the scan of ${env.label} behind this plan stopped early (${env.status}), so items it did not reach were not considered; rerun with a larger --scan-budget (for example --scan-budget 5m).`
+  );
+}
+
 export function formatAudit(audit, options = {}) {
   const limit = options.verbose ? Infinity : DEFAULT_LIMIT * 2;
   const mode = audit.dryRun ? 'dry run, nothing was deleted' : 'deleting';
@@ -527,7 +610,17 @@ export function formatAudit(audit, options = {}) {
       ? `Would free ${formatBytes(audit.plannedBytes)} (run with --yes to delete)`
       : `Freed ${formatBytes(audit.freedBytes)}`
   );
-  if (audit.file) {
+  lines.push(...incompleteScanLines(audit.incomplete));
+  const conditions = conditionsWarning(audit.blocked);
+  if (conditions) {
+    lines.push(
+      conditions,
+      ...conditionsSection(audit.blocked, options).slice(2)
+    );
+  }
+  if (audit.auditError) {
+    lines.push(`Audit log: not written (${audit.auditError.message})`);
+  } else if (audit.file) {
     lines.push(`Audit log: ${audit.file}`);
   }
   return lines.join('\n');

package/src/rules/downloads.js

@@ -184,4 +184,31 @@ export const DOWNLOAD_RULES = [
     ],
     minAge: 'stale',
   },
+  {
+    id: 'crashpad-pending-reports',
+    ecosystem: 'system',
+    description:
+      'Chromium and Electron app crash reports never sent: after a month no app uploads them',
+    tier: 'moderate',
+    aggregate: true,
+    paths: [
+      '~/Library/Application Support/*/Crashpad/pending/*',
+      ...['Google', 'Yandex', 'BraveSoftware'].map(
+        (vendor) =>
+          `~/Library/Application Support/${vendor}/*/Crashpad/pending/*`
+      ),
+      '~/.config/*/Crashpad/pending/*',
+    ],
+    minAge: 'inactive',
+  },
+  {
+    id: 'gh-run-log-cache',
+    ecosystem: 'system',
+    description:
+      'GitHub CLI cached workflow run logs: gh downloads them again while GitHub keeps them',
+    tier: 'moderate',
+    aggregate: true,
+    paths: ['~/.cache/gh/run-log-*.zip'],
+    minAge: 'stale',
+  },
 ];

package/src/rules/other.js

@@ -414,6 +414,15 @@ export const OTHER_RULES = [
     aggregate: true,
     paths: ['~/Library/Logs/DiagnosticReports/*'],
   },
+  {
+    id: 'rotated-app-logs',
+    ecosystem: 'system',
+    description:
+      'rotated app logs (warp.log.old.2, app.log.1): apps write only the current log',
+    tier: 'moderate',
+    paths: ['~/Library/Logs/*.log.*', '~/Library/Logs/*/*.log.*'],
+    minAge: 'stale',
+  },
   {
     id: 'apt-archives',
     ecosystem: 'system',

package/src/scan.js

@@ -173,6 +173,7 @@ export async function environmentContext(env, options, overrides = {}) {
   });
   const liveness = new LivenessProbe(env, {
     staleAgeMs: options.staleAgeMs,
+    inactiveMs: options.inactiveMs,
     now: options.now,
   });
   await liveness.refresh(true);
@@ -377,13 +378,20 @@ async function scanEnvironmentScoped(
       block(item, env.scanPolicy.removalReason(target));
     }
   }
-  for (const message of env.accessErrors?.values() ?? []) {
+  for (const message of await accessErrorMessages(env)) {
     errors.push({ env: env.id, scanner: 'filesystem', message });
   }
   env.scanStatus = incomplete ? 'error' : 'complete';
   return items;
 }
 
+/** Report messages for paths the scan could not inspect. */
+function accessErrorMessages(env) {
+  return env.accessErrorMessages
+    ? env.accessErrorMessages()
+    : [...(env.accessErrors?.values() ?? [])];
+}
+
 async function attributeStorage(env, items) {
   if (env.writableLayer) {
     const usages = await env.usageMany([
@@ -516,6 +524,24 @@ export function filterItems(items, options, daemons = [], pathApi) {
   );
 }
 
+/**
+ * Items that share every block with an installed app (APFS clones): they
+ * free nothing, so they are not offered, but `du` counts them at full size.
+ */
+function sharedItems(items, options, pathApi) {
+  return filterItems(
+    items.filter((item) => item.sharedWith),
+    { ...options, minSizeBytes: 0 },
+    [],
+    pathApi
+  ).map((item) => ({
+    rule: item.rule,
+    path: item.path,
+    apparentBytes: item.apparentBytes,
+    sharedWith: item.sharedWith,
+  }));
+}
+
 function envDescriptor(env, depth, chain) {
   return {
     id: env.id,
@@ -665,6 +691,7 @@ async function scanScoped(input) {
     docker?.daemons ?? [],
     env.path
   );
+  const shared = sharedItems(hostItems, options, env.path);
   const environments = [envDescriptor(env, 0, [])];
   for (const inner of docker?.environments ?? []) {
     environments.push(inner);
@@ -677,6 +704,7 @@ async function scanScoped(input) {
     options,
     env,
     items,
+    shared,
     environments,
     docker,
     errors,
@@ -707,6 +735,7 @@ export function buildReport({
   options,
   env,
   items,
+  shared = [],
   environments,
   docker,
   errors,
@@ -722,6 +751,7 @@ export function buildReport({
     options: reportOptions(options),
     environments,
     items,
+    shared,
     totals: tierTotals(items),
     docker: docker
       ? {

package/src/scanners/global.js

@@ -238,6 +238,10 @@ async function describeAppClone(context, rule, item, homes) {
   item.checks.executables = executables;
   if (sharedWith) {
     // Every block is shared with the installed app: nothing to reclaim.
+    // The report lists it under `shared` so the space `du` counts for it
+    // is explained.
+    item.sharedWith = sharedWith;
+    item.apparentBytes = item.bytes;
     item.bytes = 0;
     item.reason = `shares its disk blocks with ${sharedWith}`;
   }

package/src/scanners/node-modules.js

@@ -0,0 +1,89 @@
+/**
+ * A node_modules directory is regenerable only as far as package managers
+ * fill it. Other data kept there (verification runs, evidence, hand-made
+ * fixtures) survives no reinstall, so it keeps the whole directory.
+ */
+
+import { formatBytes } from '../units.js';
+
+/**
+ * Top-level entries package managers and the tools they run create:
+ * links, lockfile copies, store and workspace state, and caches that
+ * re-create themselves.
+ */
+const MANAGED_ENTRIES = new Set([
+  '.bin',
+  '.package-lock.json',
+  '.modules.yaml',
+  '.pnpm',
+  '.pnpm-workspace-state.json',
+  '.pnpm-workspace-state-v1.json',
+  '.yarn-state.yml',
+  '.yarn-integrity',
+  '.yarn-metadata.json',
+  '.store',
+  '.staging',
+  '.ignored',
+  '.cache',
+  '.vite',
+  '.vite-temp',
+  '.vitest',
+  '.vitest-cache',
+  '.deno',
+  '.prisma',
+  '.astro',
+  '.mf',
+  '.tmp',
+  '.DS_Store',
+]);
+
+/**
+ * Entries of `dir` no package manager installs, with their size; empty
+ * leftovers are left out.
+ * @returns {Promise<Array<{name: string, bytes: number}>>}
+ */
+export async function foreignEntries(env, dir) {
+  const candidates = [];
+  for (const entry of await env.list(dir)) {
+    if (
+      MANAGED_ENTRIES.has(entry.name) ||
+      entry.name.startsWith('@') ||
+      entry.type === 'symlink'
+    ) {
+      continue;
+    }
+    if (
+      entry.type === 'dir' &&
+      (await env.stat(env.path.join(entry.path, 'package.json')))
+    ) {
+      continue;
+    }
+    candidates.push(entry);
+  }
+  if (candidates.length === 0) {
+    return [];
+  }
+  const usages = await env.usageMany(
+    candidates.map((entry) => entry.path),
+    { cache: true }
+  );
+  return candidates
+    .map((entry) => ({ name: entry.name, usage: usages.get(entry.path) }))
+    .filter(({ usage }) => usage && (usage.files ?? 1) > 0)
+    .map(({ name, usage }) => ({ name, bytes: usage.bytes }))
+    .sort((a, b) => b.bytes - a.bytes);
+}
+
+/** Blocker naming the foreign data inside `dir`, or null. */
+export async function foreignDataBlocker(env, dir) {
+  const foreign = await foreignEntries(env, dir);
+  if (foreign.length === 0) {
+    return null;
+  }
+  const names = foreign
+    .slice(0, 3)
+    .map((entry) => `${entry.name} (${formatBytes(entry.bytes)})`)
+    .join(', ');
+  const more = foreign.length > 3 ? ` and ${foreign.length - 3} more` : '';
+  return `holds data no package manager installs: ${names}${more}; a reinstall does not re-create it, so move it out of node_modules first`;
+}

package/src/scanners/projects.js

@@ -9,6 +9,9 @@ import { scanItems } from '../env/scope.js';
  * are present. Generic names (`build`, `lib`, `target`, `bin`) that fail
  * every rule are searched again below, with the remaining depth, so a
  * non-matching `build` directory never hides real projects inside it.
+ * Git worktree folders (`.worktrees`, `worktrees`, `.claude/worktrees`)
+ * hold whole checkouts, so the search below them starts with the full
+ * depth again: an agent's worktree deep in a project is a project too.
  *
  * Cargo `target` directories additionally yield `cargo-superseded` items:
  * older build hashes that a newer build of the same unit replaced (see
@@ -20,9 +23,11 @@ import { block, makeItem } from '../items.js';
 import { isWithin, matchesGlob } from '../paths.js';
 import { listMany, scanTimeBusy } from './common.js';
 import { analyzeRustProfile, findRustProfiles } from './rust.js';
+import { foreignDataBlocker } from './node-modules.js';
 import { timed } from '../timings.js';
 
 const ECOSYSTEM_NAMES = new Map(ECOSYSTEMS.map((e) => [e.id, e.name]));
+const WORKTREE_DIRS = ['.worktrees', 'worktrees'];
 
 function anyMatch(entries, globs) {
   return (entries ?? []).some((entry) =>
@@ -37,6 +42,13 @@ function depthBelow(env, roots, target) {
   return env.path.relative(root, target).split(/[\\/]/).filter(Boolean).length;
 }
 
+/** Depth left below a directory no rule claims; worktrees start afresh. */
+function remainingDepth(env, dirs, candidate, { depth, maxDepth }) {
+  return WORKTREE_DIRS.includes(candidate.name)
+    ? maxDepth
+    : depth - depthBelow(env, dirs, candidate.path);
+}
+
 function ruleAccepts(env, rule, candidate, selfListing, grandListing) {
   if (rule.markers && !anyMatch(candidate.siblings, rule.markers)) {
     return false;
@@ -139,7 +151,9 @@ async function indexedMatches(env, roots, globs, maxDepth, rules) {
 export async function findProjectDirs(env, roots, options = {}) {
   const rules = options.rules ?? PROJECT_RULES;
   const maxDepth = options.maxDepth ?? 6;
-  const globs = [...new Set(rules.flatMap((rule) => rule.names))];
+  const globs = [
+    ...new Set([...rules.flatMap((rule) => rule.names), ...WORKTREE_DIRS]),
+  ];
   const matches = [];
   const seen = new Set();
   const accept = (match) => {
@@ -171,7 +185,10 @@ export async function findProjectDirs(env, roots, options = {}) {
           }
           continue;
         }
-        const remaining = depth - depthBelow(env, dirs, match.candidate.path);
+        const remaining = remainingDepth(env, dirs, match.candidate, {
+          depth,
+          maxDepth,
+        });
         if (remaining > 0) {
           next.set(remaining, [
             ...(next.get(remaining) ?? []),
@@ -232,6 +249,14 @@ async function projectItem(context, { candidate, rule }, usage) {
     ...projectTier(rule),
     checks: { busy: rule.busy ?? [], cwd: project, mtime: true },
   });
+  if (rule.id === 'node-modules') {
+    block(
+      item,
+      await timed(context.timings, 'projects:contents', () =>
+        foreignDataBlocker(env, candidate.path)
+      )
+    );
+  }
   await addBlockers(context, item, false);
   return item;
 }

package/src/swap.js

@@ -260,8 +260,11 @@ export function swapWarnings(swap, disk) {
   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);
+  // The kernel (PID 0) cannot be quit and this dss run ends by itself, so
+  // naming either helps nobody.
+  const candidates = swap.holders.filter(
+    (holder) => holder.pid > 0 && !holder.self
+  );
   const growing = candidates.filter(
     (holder) => holder.growth?.memoryBytes >= GROWTH_WARNING_BYTES
   );
@@ -308,6 +311,10 @@ export async function readSwap(env, options = {}) {
   if (!swap) {
     return null;
   }
+  // This dss run shows up among the holders while it scans; it ends on its own.
+  swap.holders = swap.holders.map((holder) =>
+    holder.pid === process.pid ? { ...holder, self: true } : holder
+  );
   const history = await loadSwapHistory(stateDir, now);
   const grown = withGrowth(swap, history);
   await saveSwapHistory(stateDir, [