disk-space-saviour 0.15.1 → 0.16.0

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

@@ -32,6 +32,7 @@ export const DEFAULTS = {
   yes: false,
   backupDir: null,
   auditDir: null,
+  scanBudget: '2m',
 };
 
 function toBytes(value) {
@@ -70,6 +71,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 +88,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,7 +52,7 @@ 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)`
       : '';
@@ -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),
   ];
 }
@@ -322,6 +322,12 @@ export function formatReport(report, options = {}) {
     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 && 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'],
+  },
+];

package/src/scan.js

@@ -7,9 +7,12 @@ import {
   configureContainerHost,
   resetWritableLayers,
 } from './docker/writable.js';
+import { setInterval, clearInterval } from 'node:timers';
 import { scanDocker } from './docker/scan.js';
 import { LocalEnv } from './env/local.js';
 import { configureScanPolicy } from './env/policy.js';
+import { configureCacheRoots } from './env/cache-roots.js';
+import { checkSignal, environmentScope } from './env/scope.js';
 import { block, tierTotals } from './items.js';
 import { hostExecutor, trace } from './exec.js';
 import { GitInspector } from './git.js';
@@ -59,6 +62,9 @@ const RESCAN_OPTIONS = new Set([
   'journalKeep',
   'env',
   'now',
+  'signal',
+  'scanBudget',
+  'onScanProgress',
 ]);
 
 function safetySnapshot(report) {
@@ -133,6 +139,7 @@ export async function environmentContext(env, options, overrides = {}) {
   });
   await liveness.refresh(true);
   const homes = await env.homeDirs();
+  await configureCacheRoots(env, homes);
   const tmpDirs = await env.tmpDirs();
   const roots = overrides.roots ?? (await defaultRoots(env, homes, tmpDirs));
   return {
@@ -152,16 +159,71 @@ export async function environmentContext(env, options, overrides = {}) {
  * @returns {Promise<object[]>} items
  */
 export async function scanEnvironment(env, options, extra = {}) {
-  const errors = extra.errors ?? [];
-  let context;
+  const controller = new AbortController();
+  const abort = () => controller.abort(options.signal.reason);
+  options.signal?.addEventListener('abort', abort, { once: true });
+  if (options.signal?.aborted) {
+    abort();
+  }
+  const started = Date.now(),
+    deadline = started + options.scanBudgetMs;
+  const timer = setTimeout(
+    () => controller.abort(new Error('scan time budget exceeded')),
+    options.scanBudgetMs
+  );
+  const found = new Map();
+  let scanner = 'context';
+  const progress = () =>
+    options.onScanProgress?.({
+      env: env.id,
+      scanner,
+      elapsedMs: Date.now() - started,
+      items: found.size,
+      status: env.scanStatus,
+    });
+  env.scanStatus = 'scanning';
+  const interval = setInterval(progress, 5000);
   try {
-    context = await environmentContext(env, options, extra);
+    return await environmentScope(
+      env,
+      controller.signal,
+      () => {
+        progress();
+        return scanEnvironmentScoped(env, options, extra, found, (name) => {
+          scanner = name;
+          progress();
+        });
+      },
+      deadline
+    );
   } catch (error) {
-    errors.push({ env: env.id, scanner: 'context', message: error.message });
-    return [];
+    env.scanStatus = options.signal?.aborted
+      ? 'aborted'
+      : controller.signal.aborted
+        ? 'budget-exceeded'
+        : 'error';
+    (extra.errors ?? []).push({ env: env.id, scanner, message: error.message });
+    const items = [...found.values()];
+    for (const item of items) {
+      block(item, `scan incomplete: ${error.message}`);
+    }
+    return items;
+  } finally {
+    clearTimeout(timer);
+    clearInterval(interval);
+    options.signal?.removeEventListener('abort', abort);
+    progress();
   }
-  const items = [];
+}
+
+async function scanEnvironmentScoped(env, options, extra, found, stage) {
+  const errors = extra.errors ?? [];
+  const context = await environmentContext(env, options, extra);
+  context.emit = (item) => found.set(item.id, item);
+  let incomplete = false;
   for (const name of options.scanners) {
+    checkSignal(env.signal);
+    stage(name);
     const scanner = SCANNERS[name];
     if (!scanner) {
       throw new Error(
@@ -169,13 +231,26 @@ export async function scanEnvironment(env, options, extra = {}) {
       );
     }
     const started = Date.now();
+    const previous = new Set(found.keys());
     try {
-      items.push(...(await scanner(context)));
+      const entries = await scanner(context);
+      for (const item of entries) {
+        context.emit(item);
+      }
     } catch (error) {
+      checkSignal(env.signal);
+      incomplete = true;
+      for (const [id, item] of found) {
+        if (!previous.has(id)) {
+          block(item, `scan incomplete: ${error.message}`);
+        }
+      }
       errors.push({ env: env.id, scanner: name, message: error.message });
     }
     trace('scanner', name, 'in', env.id, `${Date.now() - started}ms`);
   }
+  stage('storage');
+  const items = [...found.values()];
   await attributeStorage(env, items);
   for (const item of items) {
     for (const target of item.paths) {
@@ -185,6 +260,7 @@ export async function scanEnvironment(env, options, extra = {}) {
   for (const message of env.accessErrors?.values() ?? []) {
     errors.push({ env: env.id, scanner: 'filesystem', message });
   }
+  env.scanStatus = incomplete ? 'error' : 'complete';
   return items;
 }
 
@@ -307,6 +383,8 @@ function envDescriptor(env, depth, chain) {
     depth,
     chain,
     hint: env.probeHint ?? null,
+    scanStatus: env.scanStatus ?? null,
+    layerSource: env.writableLayer?.source ?? null,
   };
 }
 
@@ -373,6 +451,30 @@ function blockMountedHostItems(items, mounts, pathApi) {
 }
 
 export async function scan(input = {}) {
+  const env = input.env ?? new LocalEnv();
+  try {
+    return await environmentScope(env, input.signal, () =>
+      scanScoped({ ...input, env })
+    );
+  } catch (error) {
+    if (!input.signal?.aborted) {
+      throw error;
+    }
+    env.scanStatus = 'aborted';
+    const options = resolveOptions(input);
+    return buildReport({
+      options,
+      env,
+      items: [],
+      environments: [envDescriptor(env, 0, [])],
+      docker: null,
+      errors: [{ env: env.id, scanner: 'context', message: error.message }],
+      startedAt: options.now(),
+    });
+  }
+}
+
+async function scanScoped(input) {
   const options = resolveOptions(input);
   const env = input.env ?? new LocalEnv();
   const startedAt = options.now();
@@ -420,6 +522,8 @@ function reportOptions(options) {
   const serializable = { ...options };
   delete serializable.now;
   delete serializable.env;
+  delete serializable.signal;
+  delete serializable.onScanProgress;
   return serializable;
 }
 
@@ -440,6 +544,7 @@ export function buildReport({
     tool: 'disk-space-saviour',
     createdAt: new Date(options.now()).toISOString(),
     durationMs: options.now() - startedAt,
+    aborted: Boolean(options.signal?.aborted),
     host: { env: env.id, label: env.label, platform: env.platform },
     options: reportOptions(options),
     environments,

package/src/scanners/agents.js

@@ -1,3 +1,4 @@
+import { scanItems } from '../env/scope.js';
 /**
  * Snapshot stores of AI coding agents built on the opencode storage layout
  * (`@link-assistant/agent`, opencode).
@@ -112,7 +113,7 @@ async function appItems(context, app, root) {
       mtimeMs: usages.get(state.entry.path)?.newestMtimeMs ?? 0,
     }))
     .sort((a, b) => b.mtimeMs - a.mtimeMs)[0].state;
-  const items = [];
+  const items = scanItems(context);
   for (const state of states) {
     const usage = usages.get(state.entry.path);
     const verdict =
@@ -148,7 +149,7 @@ async function appItems(context, app, root) {
 export async function scanAgents(context, { apps = AGENT_APPS } = {}) {
   const { env, options } = context;
   const homes = options.homes ?? (await env.homeDirs());
-  const items = [];
+  const items = scanItems(context);
   const seen = new Set();
   for (const home of homes) {
     for (const dataDir of dataDirs(env, home)) {

package/src/scanners/common.js

@@ -26,10 +26,15 @@ export async function listMany(env, dirs) {
  * @returns {string|null}
  */
 export async function scanTimeBusy(context, item) {
-  await context.liveness?.resolve(item.paths);
+  await resolvePaths(context, item.paths);
   return context.liveness ? context.liveness.busyReason(item) : null;
 }
 
+/** Prime one batch before constructing items, so later per-item probes are cached. */
+export async function resolvePaths(context, paths) {
+  await context.liveness?.resolve(paths);
+}
+
 /**
  * Whether `now - timestamp` exceeds `windowMs` (unknown timestamps count as
  * recent, so they are never treated as abandoned).