z-clean 0.1.1 → 0.3.0

package/src/process-tree.js

@@ -0,0 +1,338 @@
+'use strict';
+
+const { execSync } = require('child_process');
+const os = require('os');
+const { readCIMProcesses, readWMICProcesses } = require('./windows-processes');
+
+const platform = os.platform();
+
+/**
+ * In-memory process tree for O(1) PID lookup and O(depth) ancestor traversal.
+ * Built from one platform enumeration call sequence — zero execSync during queries.
+ *
+ * Usage:
+ *   const tree = ProcessTree.build();      // platform auto-detect
+ *   tree.isOrphan(pid)                     // no execSync
+ *   tree.hasAncestorMatching(pid, testFn)  // no execSync
+ */
+class ProcessTree {
+  /**
+   * @param {Array<{pid: number, ppid: number, cmd: string, mem: number, age: number, startTime: string|null}>} processes
+   */
+  constructor(processes, diagnostics = {}) {
+    this.warnings = Array.isArray(diagnostics.warnings) ? diagnostics.warnings : [];
+    this.errors = Array.isArray(diagnostics.errors) ? diagnostics.errors : [];
+    this.platform = diagnostics.platform || platform;
+
+    /** @type {Map<number, object>} */
+    this.byPid = new Map();
+    /** @type {Map<number, number[]>} pid → [childPids] */
+    this.childrenMap = new Map();
+
+    for (const proc of processes) {
+      this.byPid.set(proc.pid, proc);
+      if (!this.childrenMap.has(proc.ppid)) {
+        this.childrenMap.set(proc.ppid, []);
+      }
+      this.childrenMap.get(proc.ppid).push(proc.pid);
+    }
+  }
+
+  /**
+   * O(1) lookup by PID.
+   * @returns {object|null}
+   */
+  get(pid) {
+    return this.byPid.get(pid) || null;
+  }
+
+  /**
+   * Parent process info, or null if PID not in tree or parent unknown.
+   * @returns {object|null}
+   */
+  parent(pid) {
+    const proc = this.byPid.get(pid);
+    if (!proc) return null;
+    return this.byPid.get(proc.ppid) || null;
+  }
+
+  /**
+   * Array of direct child process infos.
+   * @returns {object[]}
+   */
+  children(pid) {
+    const childPids = this.childrenMap.get(pid) || [];
+    return childPids.map((cpid) => this.byPid.get(cpid)).filter(Boolean);
+  }
+
+  /**
+   * Ancestor chain starting from the direct parent, root last.
+   * Stops at PID 1 or when the parent is not in the tree.
+   * @returns {object[]}
+   */
+  ancestors(pid) {
+    const result = [];
+    const visited = new Set();
+    let current = this.byPid.get(pid);
+
+    while (current) {
+      if (visited.has(current.pid)) break;
+      visited.add(current.pid);
+      const par = this.byPid.get(current.ppid);
+      if (!par) break;
+      result.push(par);
+      current = par;
+    }
+
+    return result;
+  }
+
+  /**
+   * Determine orphan status from in-memory tree — no execSync.
+   *
+   * @returns {{ isOrphan: boolean, ppid: number|null, reason: string }}
+   */
+  isOrphan(pid) {
+    const proc = this.byPid.get(pid);
+    if (!proc) return { isOrphan: false, ppid: null, reason: 'not-in-tree' };
+
+    const { ppid } = proc;
+
+    if (this.platform === 'win32') {
+      if (!this.byPid.has(ppid)) {
+        return { isOrphan: true, ppid, reason: 'parent-gone' };
+      }
+      return { isOrphan: false, ppid, reason: 'has-parent' };
+    }
+
+    // macOS: PPID 1 = reparented to launchd
+    if (this.platform === 'darwin' && ppid === 1) {
+      return { isOrphan: true, ppid: 1, reason: 'reparented-to-launchd' };
+    }
+
+    // Linux: PPID 1 = reparented to init
+    if (this.platform === 'linux' && ppid === 1) {
+      return { isOrphan: true, ppid: 1, reason: 'reparented-to-init' };
+    }
+
+    // Linux: parent is systemd --user (user session slice)
+    if (this.platform === 'linux' && ppid > 1) {
+      const parentProc = this.byPid.get(ppid);
+      if (parentProc) {
+        // Extract process name (basename of first token)
+        const comm = parentProc.cmd.split(/\s+/)[0].split('/').pop();
+        if (comm === 'systemd') {
+          return { isOrphan: true, ppid, reason: 'reparented-to-systemd-user' };
+        }
+      }
+    }
+
+    // Has living parent in the tree
+    if (this.byPid.has(ppid)) {
+      return { isOrphan: false, ppid, reason: 'has-parent' };
+    }
+
+    // Parent not in tree and not PID 1 — likely died
+    return { isOrphan: true, ppid, reason: 'parent-gone' };
+  }
+
+  /**
+   * Walk ancestor chain, return true if any ancestor passes testFn.
+   * Cycle-safe via visited Set. Stops at PID 1 or when parent not in tree.
+   *
+   * @param {number} pid
+   * @param {(proc: object) => boolean} testFn
+   * @returns {boolean}
+   */
+  hasAncestorMatching(pid, testFn) {
+    const visited = new Set();
+    let current = this.byPid.get(pid);
+
+    while (current) {
+      if (visited.has(current.pid)) break; // cycle protection
+      visited.add(current.pid);
+
+      const parent = this.byPid.get(current.ppid);
+      if (!parent || parent.pid === 1) break;
+
+      if (testFn(parent)) return true;
+      current = parent;
+    }
+
+    return false;
+  }
+
+  /**
+   * Unix: build ProcessTree from a single `ps` call.
+   * Format: pid= ppid= rss= etime= lstart= command=
+   *
+   * @returns {ProcessTree}
+   */
+  static fromPS(options = {}) {
+    const runtime = runtimeOptions(options);
+    let output;
+    try {
+      // LC_ALL=C forces English date output in lstart= regardless of system locale
+      output = runtime.execSync('LC_ALL=C ps -eo pid=,ppid=,rss=,etime=,lstart=,command=', {
+        encoding: 'utf-8',
+        timeout: 10000,
+        maxBuffer: 10 * 1024 * 1024,
+      });
+    } catch (err) {
+      return new ProcessTree([], {
+        platform: runtime.platform,
+        errors: [providerDiagnostic('ps', 'process-enumeration-provider-failed', err)],
+      });
+    }
+
+    const processes = [];
+    const myPid = runtime.currentPid;
+
+    for (const line of output.trim().split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+
+      // Format: PID PPID RSS ELAPSED [DAY ]MON DD HH:MM:SS YEAR COMMAND
+      // Example: "  123  456  2048  01:23:45  Mon Jan  1 12:00:00 2024  node server.js"
+      const match = trimmed.match(
+        /^\s*(\d+)\s+(\d+)\s+(\d+)\s+([\d:.-]+)\s+\w+\s+(\w+\s+\d+\s+[\d:]+\s+\d+)\s+(.+)$/
+      );
+      if (!match) continue;
+
+      const pid = parseInt(match[1], 10);
+      if (pid === myPid) continue;
+
+      const ppid = parseInt(match[2], 10);
+      const rssKB = parseInt(match[3], 10);
+      const elapsed = match[4];
+      const lstart = match[5];
+      const cmd = match[6];
+
+      let startTime = null;
+      try { startTime = new Date(lstart).toISOString(); } catch { /* ignore */ }
+
+      processes.push({
+        pid,
+        ppid,
+        cmd,
+        mem: rssKB * 1024, // KB → bytes
+        age: parseElapsed(elapsed),
+        startTime,
+      });
+    }
+
+    return new ProcessTree(processes, { platform: runtime.platform });
+  }
+
+  static fromWMIC(options = {}) {
+    const runtime = runtimeOptions({ ...options, platform: 'win32' });
+    const result = readWMICProcesses(runtime);
+    return new ProcessTree(result.processes, {
+      platform: runtime.platform,
+      warnings: result.warnings,
+    });
+  }
+
+  static fromCIM(options = {}) {
+    const runtime = runtimeOptions({ ...options, platform: 'win32' });
+    const result = readCIMProcesses(runtime);
+    return new ProcessTree(result.processes, {
+      platform: runtime.platform,
+      warnings: result.warnings,
+    });
+  }
+
+  static fromWindows(options = {}) {
+    const runtime = runtimeOptions({ ...options, platform: 'win32' });
+    const wmic = readWMICProcesses(runtime);
+    if (wmic.processes.length > 0) {
+      return new ProcessTree(wmic.processes, { platform: runtime.platform });
+    }
+
+    const warnings = [...wmic.warnings];
+    const cim = readCIMProcesses(runtime);
+    if (cim.processes.length > 0) {
+      return new ProcessTree(cim.processes, {
+        platform: runtime.platform,
+        warnings: warnings.concat(cim.warnings),
+      });
+    }
+
+    warnings.push(...cim.warnings);
+    return new ProcessTree([], {
+      platform: runtime.platform,
+      warnings,
+      errors: [{
+        code: 'process-enumeration-failed',
+        platform: 'win32',
+        providers: ['cim', 'wmic'],
+        message: 'Windows process enumeration failed for all providers.',
+      }],
+    });
+  }
+
+  /**
+   * Platform-aware factory. Use this from scanner/orphan/whitelist.
+   * Calls fromWindows() on Windows, fromPS() everywhere else.
+   *
+   * @returns {ProcessTree}
+   */
+  static build(options = {}) {
+    const runtime = runtimeOptions(options);
+    return runtime.platform === 'win32'
+      ? ProcessTree.fromWindows(runtime)
+      : ProcessTree.fromPS(runtime);
+  }
+}
+
+function runtimeOptions(options = {}) {
+  return {
+    execSync: options.execSync || execSync,
+    platform: options.platform || platform,
+    currentPid: options.currentPid || process.pid,
+    now: options.now || Date.now(),
+  };
+}
+
+function providerDiagnostic(provider, code, err) {
+  return {
+    code,
+    provider,
+    message: err instanceof Error ? err.message : String(err || ''),
+  };
+}
+
+/**
+ * Parse ps elapsed time format: [[DD-]HH:]MM:SS
+ * Moved here from scanner.js to co-locate with ProcessTree.
+ *
+ * @param {string} elapsed
+ * @returns {number} milliseconds
+ */
+function parseElapsed(elapsed) {
+  if (!elapsed) return 0;
+
+  let days = 0;
+  let rest = elapsed.trim();
+
+  const dayMatch = rest.match(/^(\d+)-(.+)$/);
+  if (dayMatch) {
+    days = parseInt(dayMatch[1], 10);
+    rest = dayMatch[2];
+  }
+
+  const parts = rest.split(':').map((p) => parseInt(p, 10));
+
+  let hours = 0, minutes = 0, seconds = 0;
+  if (parts.length === 3) {
+    [hours, minutes, seconds] = parts;
+  } else if (parts.length === 2) {
+    [minutes, seconds] = parts;
+  } else if (parts.length === 1) {
+    [seconds] = parts;
+  }
+
+  return ((days * 24 + hours) * 3600 + minutes * 60 + seconds) * 1000;
+}
+
+module.exports = { ProcessTree, parseElapsed };

package/src/reporter.js

@@ -65,10 +65,54 @@ function truncate(str, maxLen = 80) {
   return str.substring(0, maxLen - 3) + '...';
 }
 
+function getDiagnostics(result) {
+  return {
+    warnings: Array.isArray(result?.warnings) ? result.warnings : [],
+    errors: Array.isArray(result?.errors) ? result.errors : [],
+  };
+}
+
+function formatDiagnostic(item) {
+  if (typeof item === 'string') return item;
+  const code = item.code ? `${item.code}: ` : '';
+  const providers = Array.isArray(item.providers) && item.providers.length > 0
+    ? ` (providers: ${item.providers.join(', ')})`
+    : '';
+  return `${code}${item.message || 'process scan diagnostic'}${providers}`;
+}
+
+function reportScanDiagnostics(result) {
+  const { warnings, errors } = getDiagnostics(result);
+
+  if (warnings.length > 0) {
+    console.log(c('yellow', '  Scan warnings:'));
+    for (const warning of warnings) {
+      console.log(`    ${formatDiagnostic(warning)}`);
+    }
+    console.log();
+  }
+
+  if (errors.length > 0) {
+    console.log(c('red', '  Process enumeration failed. Scan results are incomplete.'));
+    for (const error of errors) {
+      console.log(`    ${formatDiagnostic(error)}`);
+    }
+    console.log();
+    return true;
+  }
+
+  return false;
+}
+
 /**
  * Report dry-run scan results.
  */
 function reportDryRun(zombies) {
+  if (reportScanDiagnostics(zombies)) {
+    console.log(c('yellow', '  Cleanup skipped because zclean could not inspect the process list safely.\n'));
+    return;
+  }
+
   if (zombies.length === 0) {
     console.log(c('green', '  No zombie processes found. System is clean.'));
     return;
@@ -93,7 +137,7 @@ function reportDryRun(zombies) {
  * Report kill results.
  */
 function reportKill(results) {
-  const { killed, failed, skipped } = results;
+  const { killed, failed, skipped, warning } = results;
 
   if (killed.length === 0 && failed.length === 0 && skipped.length === 0) {
     console.log(c('green', '  No zombie processes to clean.'));
@@ -102,6 +146,11 @@ function reportKill(results) {
 
   console.log();
 
+  if (warning) {
+    console.log(c('yellow', `  ${warning}`));
+    console.log();
+  }
+
   if (killed.length > 0) {
     const totalMem = killed.reduce((sum, p) => sum + p.mem, 0);
     console.log(c('green', `  Killed ${killed.length} zombie process${killed.length === 1 ? '' : 'es'}:`));
@@ -109,6 +158,13 @@ function reportKill(results) {
       console.log(`    ${c('green', 'KILLED')} PID ${String(p.pid).padStart(6)}  ${p.name.padEnd(16)}  ${formatBytes(p.mem).padStart(8)}`);
     }
     console.log(c('green', `\n  Memory freed: ${formatBytes(totalMem)}`));
+
+    // Show cumulative stats if available
+    if (results.cumulative) {
+      const s = results.cumulative;
+      console.log(c('gray', `  This week: ${s.weekKilled} cleaned, ${formatBytes(s.weekMemFreed)} freed`));
+      console.log(c('gray', `  All time:  ${s.totalKilled} cleaned, ${formatBytes(s.totalMemFreed)} freed`));
+    }
   }
 
   if (skipped.length > 0) {
@@ -135,7 +191,9 @@ function reportStatus(zombies, logs) {
   console.log(bold('\n  zclean status\n'));
 
   // Current zombies
-  if (zombies.length === 0) {
+  if (reportScanDiagnostics(zombies)) {
+    console.log(c('red', '  Current zombies: unknown'));
+  } else if (zombies.length === 0) {
     console.log(c('green', '  Current zombies: 0'));
   } else {
     console.log(c('yellow', `  Current zombies: ${zombies.length}`));
@@ -212,6 +270,7 @@ module.exports = {
   reportStatus,
   reportLogs,
   reportConfig,
+  reportScanDiagnostics,
   formatBytes,
   formatDuration,
   C,