disk-space-saviour 0.15.2 → 0.17.0

package/src/fast-clean.js

@@ -0,0 +1,39 @@
+/** Clean completed safe host findings while discovery continues. */
+import { clean } from './clean.js';
+import { scan } from './scan.js';
+
+export async function cleanDuringScan(options) {
+  const entries = [];
+  const health = [];
+  let failure;
+  const report = await scan({
+    ...options,
+    onScanPhase: async (phase) => {
+      try {
+        const audit = await clean(phase, {
+          ...options,
+          tier: 'safe',
+          priorEntries: entries,
+          priorHealth: health,
+        });
+        entries.splice(0, entries.length, ...audit.entries);
+        health.splice(0, health.length, ...audit.health);
+      } catch (error) {
+        failure = error;
+        return false;
+      }
+    },
+  });
+  if (failure) {
+    throw failure;
+  }
+  if (report.aborted) {
+    return { report, audit: null };
+  }
+  const audit = await clean(report, {
+    ...options,
+    priorEntries: entries,
+    priorHealth: health,
+  });
+  return { report, audit };
+}

package/src/health.js

@@ -52,8 +52,14 @@ function identity(proc) {
  * Processes worth watching: PID 1 and every agent or build tool.
  * @param {object[]} processes output of `env.processes()`
  */
-export function watchedProcesses(processes) {
+export function watchedProcesses(processes, mountNamespace = null) {
   return processes
+    .filter(
+      (proc) =>
+        !mountNamespace ||
+        !proc.mountNamespace ||
+        proc.mountNamespace === mountNamespace
+    )
     .filter((proc) => proc.pid === 1 || matchingName(proc, WATCHED_NAMES))
     .map(identity);
 }
@@ -101,9 +107,9 @@ function describe(lost) {
  * Per-environment snapshots and re-checks. `records` is the audit view.
  */
 export class HealthWatch {
-  constructor() {
-    this.records = [];
-    this.byEnv = new Map();
+  constructor(records = []) {
+    this.records = [...records];
+    this.byEnv = new Map(records.map((record) => [record.env, record]));
   }
 
   /**
@@ -118,7 +124,12 @@ export class HealthWatch {
       env: item.env,
       envLabel: item.envLabel,
       checks: 0,
-      watched: processes ? watchedProcesses(processes) : [],
+      watched: processes
+        ? watchedProcesses(
+            processes,
+            env.kind === 'host' ? env.mountNamespace : null
+          )
+        : [],
       available: Boolean(processes),
       lost: [],
       stopped: null,

package/src/index.d.ts

@@ -11,6 +11,25 @@ export interface ScanOptions {
   roots?: string[] | string | null;
   /** Directory depth for project search. */
   maxDepth?: number;
+  /** Time budget per filesystem environment (`2m`); incomplete findings are kept. */
+  scanBudget?: Duration;
+  /** Persistent scan/index directory. Library default is false; CLI uses XDG state. */
+  cacheDir?: string | false;
+  /** Use verified Spotlight/locate hints before the discovery walk. */
+  platformIndex?: boolean;
+  signal?: AbortSignal;
+  onScanProgress?: (progress: {
+    env: string;
+    scanner: string;
+    elapsedMs: number;
+    items: number;
+    candidates: number;
+    filesSized: number;
+    directoriesSized: number;
+    indexHits: number;
+    sizeCacheHits: number;
+    status: string;
+  }) => void;
   /** Activity window: newer files are kept (`1h`). */
   staleAge?: Duration;
   /** Alias of `staleAge`. */
@@ -65,7 +84,6 @@ export interface CleanOptions extends ScanOptions {
   confirm?: (item: Item) => boolean | Promise<boolean>;
   /** `false` skips writing the audit log file. */
   audit?: boolean;
-  signal?: AbortSignal;
   onEntry?: (entry: AuditEntry, item: Item) => void;
 }
 
@@ -100,6 +118,8 @@ export interface Item {
   path: string | null;
   paths: string[];
   bytes: number;
+  /** Cached size is advisory; cleanup always measures again. */
+  sizeEstimated?: boolean;
   /** Merged filesystem bytes, including image data, when measured in Docker. */
   totalBytes?: number;
   /** Immutable image bytes excluded from reclaimable totals. */
@@ -145,11 +165,36 @@ export interface EnvironmentDescriptor {
   chain: Array<{ containerId: string; name: string }>;
   hint?: string | null;
   disk?: Disk | null;
+  swap?: {
+    total: number;
+    used: number;
+    free: number;
+    holders: Array<{
+      pid: number;
+      command: string;
+      memoryBytes: number;
+      compressedBytes: number;
+    }>;
+    attribution: string;
+    advice: string;
+  } | null;
+  scanStatus?:
+    | 'scanning'
+    | 'complete'
+    | 'goal-reached'
+    | 'aborted'
+    | 'budget-exceeded'
+    | 'error'
+    | null;
+  layerSource?: string | null;
 }
 
 export interface TierTotal {
   items: number;
   bytes: number;
+  /** Visible blocked bytes, including data whose writable size is unknown. */
+  totalBytes?: number;
+  unknownBytes?: number;
 }
 
 export interface Report {
@@ -157,6 +202,9 @@ export interface Report {
   tool: 'disk-space-saviour';
   createdAt: string;
   durationMs: number;
+  aborted?: boolean;
+  authentication?: { hostname: string; uid: number | string; digest: string };
+  audit?: { file: string | null; error: string; code?: string };
   host: { env: string; label: string; platform: string };
   options: Record<string, unknown>;
   environments: EnvironmentDescriptor[];
@@ -188,6 +236,8 @@ export interface AuditEntry {
   reason: string | null;
   plannedBytes: number;
   freedBytes: number;
+  /** True when authoritative before/after allocation could not be measured. */
+  freedEstimated?: boolean;
   durationMs: number;
   backup?: string;
   [key: string]: unknown;
@@ -211,6 +261,7 @@ export interface AuditLog {
   startedAt: string;
   finishedAt: string | null;
   aborted?: boolean;
+  report?: Partial<Report>;
   error?: string;
   entries: AuditEntry[];
   freedBytes: number;

package/src/items.js

@@ -100,11 +100,17 @@ export function tierTotals(items) {
       Boolean(item.requiresConfirmation)
     )
   );
+  const blocked = dropNested(items.filter((item) => item.blockers.length > 0));
   totals.blocked = {
     items: items.filter((item) => item.blockers.length > 0).length,
-    bytes: items
-      .filter((item) => item.blockers.length > 0)
-      .reduce((sum, item) => sum + item.bytes, 0),
+    bytes: blocked.reduce((sum, item) => sum + item.bytes, 0),
+    totalBytes: blocked.reduce(
+      (sum, item) => sum + (item.totalBytes ?? item.bytes),
+      0
+    ),
+    unknownBytes: blocked
+      .filter((item) => item.sizeUnknown)
+      .reduce((sum, item) => sum + (item.totalBytes ?? item.bytes), 0),
   };
   return totals;
 }

package/src/liveness.js

@@ -20,6 +20,46 @@ import { formatDuration } from './units.js';
 
 const PROC_COMM_LIMIT = 15;
 
+function uncertaintyRoots(proc) {
+  const roots = processArgs(proc).flatMap((arg) => {
+    const value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : arg;
+    return value.startsWith('/') ? [value] : [];
+  });
+  if (proc.name === 'dockerd') {
+    roots.push('/var/lib/docker', '/run');
+  }
+  if (proc.name === 'containerd') {
+    roots.push('/var/lib/containerd', '/run/containerd');
+  }
+  return roots;
+}
+
+function couldAccess(proc, stat) {
+  return (
+    proc.uid === 0 ||
+    typeof proc.uid !== 'number' ||
+    !stat ||
+    stat.uid === undefined ||
+    stat.uid === proc.uid ||
+    stat.mode === undefined ||
+    (stat.mode & 0o007) !== 0 ||
+    // Group bits can also be an ACL mask granting another named identity.
+    (stat.mode & 0o070) !== 0
+  );
+}
+
+function ancestors(target, pathApi) {
+  const result = [];
+  for (
+    let dir = pathApi.dirname(target);
+    dir !== pathApi.dirname(dir);
+    dir = pathApi.dirname(dir)
+  ) {
+    result.push(dir);
+  }
+  return result;
+}
+
 function nameMatches(name, candidate) {
   return (
     name === candidate ||
@@ -131,6 +171,7 @@ export class LivenessProbe {
     this.probeError = false;
     this.realPaths = new Map();
     this.pathOwners = new Map();
+    this.pathStats = new Map();
   }
 
   async refresh(force = false) {
@@ -145,6 +186,9 @@ export class LivenessProbe {
       (processes === null || this.openPaths === null) &&
       (this.env.platform === 'linux' || this.env.platform === 'darwin');
     this.refreshedAt = this.now();
+    this.realPaths.clear();
+    this.pathStats.clear();
+    this.pathOwners.clear();
   }
 
   /** Processes of the last refresh, or null when they could not be listed. */
@@ -159,18 +203,46 @@ export class LivenessProbe {
    * @param {string[]} paths
    */
   async resolve(paths) {
-    if (this.env.unreadableProcesses?.length && this.env.stat) {
-      for (const target of paths) {
-        this.pathOwners.set(target, (await this.env.stat(target))?.uid);
+    if (this.env.unreadableProcesses?.length) {
+      const missing = [
+        ...new Set(
+          paths.flatMap((target) => [
+            target,
+            ...ancestors(target, this.env.path),
+          ])
+        ),
+      ].filter((target) => !this.pathStats.has(target));
+      const stats = this.env.statMany
+        ? await this.env.statMany(missing)
+        : new Map(
+            await Promise.all(
+              missing.map(async (target) => [
+                target,
+                await this.env.stat?.(target),
+              ])
+            )
+          );
+      for (const target of missing) {
+        this.pathStats.set(target, stats.get(target));
+        this.pathOwners.set(target, stats.get(target)?.uid);
       }
     }
-    if (typeof this.env.realPath !== 'function') {
+    if (!this.env.realPath && !this.env.realPathMany) {
       return;
     }
-    for (const target of paths) {
-      if (!this.realPaths.has(target)) {
-        this.realPaths.set(target, await this.env.realPath(target));
-      }
+    const missing = paths.filter((target) => !this.realPaths.has(target));
+    const resolved = this.env.realPathMany
+      ? await this.env.realPathMany(missing)
+      : new Map(
+          await Promise.all(
+            missing.map(async (target) => [
+              target,
+              await this.env.realPath(target),
+            ])
+          )
+        );
+    for (const target of missing) {
+      this.realPaths.set(target, resolved.get(target) ?? null);
     }
   }
 
@@ -271,29 +343,25 @@ export class LivenessProbe {
   uncertainUsage(paths) {
     for (const proc of this.env.unreadableProcesses ?? []) {
       const args = processArgs(proc);
-      const roots = args.flatMap((arg) => {
-        const value = arg.includes('=') ? arg.slice(arg.indexOf('=') + 1) : arg;
-        return value.startsWith('/') ? [value] : [];
-      });
-      if (proc.name === 'dockerd') {
-        roots.push('/var/lib/docker', '/run');
-      }
-      if (proc.name === 'containerd') {
-        roots.push('/var/lib/containerd', '/run/containerd');
-      }
+      const roots = uncertaintyRoots(proc);
+      const scopedDaemon =
+        proc.uid === 0 &&
+        ['dockerd', 'containerd'].includes(proc.name) &&
+        args.length > 0;
       for (const target of paths) {
         const intersects = roots.some(
           (root) =>
             isWithin(root, target, this.env.path) ||
             isWithin(target, root, this.env.path)
         );
-        const owner = this.pathOwners.get(target);
-        if (
-          intersects ||
-          proc.uid === null ||
-          owner === undefined ||
-          owner === proc.uid
-        ) {
+        if (scopedDaemon && !intersects) {
+          continue;
+        }
+        if (!intersects && this.inaccessible(proc, target)) {
+          continue;
+        }
+        const stat = this.pathStats.get(target);
+        if (intersects || couldAccess(proc, stat)) {
           return `unreadable process ${proc.name || 'unknown'} (pid ${proc.pid}, uid ${proc.uid ?? 'unknown'}) may use ${target}`;
         }
       }
@@ -301,6 +369,25 @@ export class LivenessProbe {
     return null;
   }
 
+  inaccessible(proc, target) {
+    if (proc.uid === 0 || typeof proc.uid !== 'number') {
+      return false;
+    }
+    return ancestors(target, this.env.path).some((dir) => {
+      const stat = this.pathStats.get(dir);
+      if (
+        !stat ||
+        stat.mode === undefined ||
+        stat.uid === proc.uid ||
+        stat.mode & 0o001
+      ) {
+        return false;
+      }
+      const groupAccess = stat.mode & 0o010;
+      return !groupAccess;
+    });
+  }
+
   /**
    * First reason the item is busy, or null when it is idle. Items with
    * `checks.perPath` leave open files to `openPathsOf`: the caller skips

package/src/options.js

@@ -16,7 +16,7 @@ export const DEFAULTS = {
   docker: null,
   dockerDepth: 3,
   containers: [],
-  scanners: ['projects', 'global', 'versions', 'agents', 'system'],
+  scanners: ['global', 'projects', 'versions', 'agents', 'system'],
   only: [],
   exclude: [],
   includeVolumes: false,
@@ -32,6 +32,9 @@ export const DEFAULTS = {
   yes: false,
   backupDir: null,
   auditDir: null,
+  scanBudget: '2m',
+  cacheDir: false,
+  platformIndex: true,
 };
 
 function toBytes(value) {
@@ -70,6 +73,10 @@ export function resolveOptions(input = {}) {
     }
   }
   const staleAge = input.olderThan ?? merged.staleAge;
+  const scanBudgetMs = toMs(merged.scanBudget);
+  if (!Number.isFinite(scanBudgetMs) || scanBudgetMs <= 0) {
+    throw new Error('scanBudget must be a positive finite duration');
+  }
   const roots = toList(merged.roots);
   return {
     ...merged,
@@ -83,6 +90,7 @@ export function resolveOptions(input = {}) {
         ? null
         : toMs(merged.investigationMaxAge),
     minSizeBytes: toBytes(merged.minSize),
+    scanBudgetMs,
     journalKeepBytes: toBytes(merged.journalKeep),
     containerFilter: toList(merged.containers),
     allowDirtyContainers: toList(merged.allowDirtyContainers),

package/src/report.js

@@ -52,11 +52,11 @@ function itemLine(item, showEnv) {
     ? `  (needs ${consentFlag(item)})`
     : '';
   const storage = item.sizeUnknown
-    ? '  (may be in an image layer; freeable bytes unknown, excluded from totals)'
+    ? `  (${formatBytes(item.totalBytes ?? 0)} visible; may be in an image layer; freeable bytes unknown, excluded from totals)`
     : item.imageBytes
       ? `  (${formatBytes(item.imageBytes)} in image${item.imageRef ? ` ${item.imageRef}` : ''}; 0 B of that data freeable now; remove the stopped container and unused image after the task completes)`
       : '';
-  return `  ${pad(formatBytes(item.bytes), 10)}  ${env}${item.rule}  ${itemLocation(item)}${confirm}${storage}`;
+  return `  ${pad(formatBytes(item.bytes), 10)}${item.sizeEstimated ? ' (estimated)' : ''}  ${env}${item.rule}  ${itemLocation(item)}${confirm}${storage}`;
 }
 
 function limited(lines, limit) {
@@ -102,7 +102,7 @@ function blockedSection(report, options) {
   }
   return [
     '',
-    `BLOCKED  ${plural(items.length, 'item')} (kept)`,
+    `BLOCKED  ${plural(items.length, 'item')} (kept), ${formatBytes(report.totals.blocked.bytes)} known writable, ${formatBytes(report.totals.blocked.totalBytes ?? report.totals.blocked.bytes)} visible${report.totals.blocked.unknownBytes ? ` (${formatBytes(report.totals.blocked.unknownBytes)} with unknown writable size)` : ''}`,
     ...limited(lines, options.limit * 2),
   ];
 }
@@ -318,10 +318,32 @@ 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)`
+    );
+    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(host.swap.advice);
+  }
   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}`);
     }

package/src/rules/toolchains.js

@@ -0,0 +1,66 @@
+/** Download leftovers of language version managers; installed runtimes are kept. */
+export const TOOLCHAIN_CACHE_RULES = [
+  {
+    id: 'perlbrew-build',
+    ecosystem: 'scripting',
+    description: 'perlbrew build trees and source archives',
+    paths: [
+      '~/perl5/perlbrew/build',
+      '~/perl5/perlbrew/dists',
+      '~/.perl5/build',
+      '~/.perl5/dists',
+    ],
+    aggregate: true,
+    busy: ['perlbrew', 'perl', 'make'],
+    native: {
+      tool: 'perlbrew',
+      argv: ['perlbrew', 'clean'],
+      cacheRoot: '~/perl5/perlbrew',
+    },
+  },
+  {
+    id: 'sdkman-tmp',
+    ecosystem: 'jvm',
+    description: 'SDKMAN download leftovers',
+    paths: ['~/.sdkman/tmp/*'],
+    aggregate: true,
+    busy: ['sdk', 'sdkman', 'java', 'curl', 'unzip'],
+    native: {
+      tool: 'bash',
+      init: '~/.sdkman/bin/sdkman-init.sh',
+      command: 'sdk flush tmp',
+    },
+  },
+  {
+    id: 'sdkman-archives',
+    ecosystem: 'jvm',
+    description: 'SDKMAN downloaded archives',
+    paths: ['~/.sdkman/archives/*'],
+    aggregate: true,
+    busy: ['sdk', 'sdkman', 'java', 'curl', 'unzip'],
+  },
+  {
+    id: 'nvm-cache',
+    ecosystem: 'javascript',
+    description: 'nvm downloaded Node archives',
+    paths: ['~/.nvm/.cache'],
+    busy: ['nvm', 'node', 'curl'],
+    native: { tool: 'sh', init: '~/.nvm/nvm.sh', command: 'nvm cache clear' },
+  },
+  {
+    id: 'ruby-gem-cache',
+    ecosystem: 'ruby',
+    description: 'downloaded Ruby gem archives',
+    paths: [
+      '~/.rbenv/versions/*/lib/ruby/gems/*/cache/*.gem',
+      '~/.rvm/gems/*/cache/*.gem',
+      '~/.local/share/gem/ruby/*/cache/*.gem',
+      '~/.gem/ruby/*/cache/*.gem',
+      '{GEM_HOME}/cache/*.gem',
+      '{GEM_PATH}/cache/*.gem',
+    ],
+    aggregate: true,
+    fileOnly: true,
+    busy: ['gem', 'bundle', 'ruby'],
+  },
+];