@photostructure/fs-metadata 0.6.0 → 0.7.0

package/src/test-utils/benchmark-harness.ts

@@ -0,0 +1,192 @@
+import { getTimingMultiplier } from "./test-timeout-config";
+
+export interface BenchmarkOptions {
+  /**
+   * Target duration for the benchmark in milliseconds (default: 20000ms / 20 seconds)
+   */
+  targetDurationMs?: number;
+
+  /**
+   * Maximum timeout for the entire benchmark in milliseconds (default: 60000ms / 1 minute)
+   */
+  maxTimeoutMs?: number;
+
+  /**
+   * Minimum iterations to run regardless of timing (default: 5)
+   */
+  minIterations?: number;
+
+  /**
+   * Maximum iterations to run regardless of timing (default: 10000)
+   */
+  maxIterations?: number;
+
+  /**
+   * Number of warmup iterations before timing (default: 2)
+   */
+  warmupIterations?: number;
+
+  /**
+   * Whether to log debug information (default: false)
+   */
+  debug?: boolean;
+}
+
+export interface BenchmarkResult {
+  /**
+   * Number of iterations actually performed
+   */
+  iterations: number;
+
+  /**
+   * Total duration in milliseconds
+   */
+  totalDurationMs: number;
+
+  /**
+   * Average duration per iteration in milliseconds
+   */
+  avgIterationMs: number;
+
+  /**
+   * Whether the benchmark hit the timeout
+   */
+  timedOut: boolean;
+}
+
+/**
+ * Runs a benchmark operation adaptively based on the performance of the test environment.
+ *
+ * This harness:
+ * 1. Runs warmup iterations to estimate operation time
+ * 2. Calculates how many iterations can fit within the target duration
+ * 3. Runs the calculated number of iterations with a safety timeout
+ *
+ * @param operation - The async function to benchmark (should be a single iteration)
+ * @param options - Configuration options for the benchmark
+ * @returns Results of the benchmark run
+ */
+export async function runAdaptiveBenchmark(
+  operation: () => Promise<void>,
+  options: BenchmarkOptions = {},
+): Promise<BenchmarkResult> {
+  const {
+    targetDurationMs = 20_000,
+    maxTimeoutMs = 60_000,
+    minIterations = 5,
+    maxIterations = 10_000,
+    warmupIterations = 2,
+  } = options;
+
+  // Apply timing multiplier based on environment
+  const multiplier = getTimingMultiplier();
+  const adjustedTargetMs = targetDurationMs * multiplier;
+  const adjustedTimeoutMs = maxTimeoutMs * multiplier;
+
+  // Debug logging removed to prevent 'Cannot log after tests are done' errors
+
+  // Run warmup iterations
+
+  const warmupStart = Date.now();
+  for (let i = 0; i < warmupIterations; i++) {
+    await operation();
+  }
+  const warmupDuration = Date.now() - warmupStart;
+  const avgWarmupTime = warmupDuration / warmupIterations;
+
+  // Warmup timing debug info removed to prevent console logging issues
+
+  // Calculate target iterations based on warmup timing
+  // Add 10% safety margin to avoid overshooting
+  const safetyMargin = 0.9;
+  let targetIterations = Math.floor(
+    (adjustedTargetMs * safetyMargin) / avgWarmupTime,
+  );
+
+  // Clamp to min/max bounds
+  targetIterations = Math.max(
+    minIterations,
+    Math.min(maxIterations, targetIterations),
+  );
+
+  // Target iterations debug info removed to prevent console logging issues
+
+  // Set up timeout promise
+  let timeoutHandle: NodeJS.Timeout | undefined;
+  const timeoutPromise = new Promise<void>((_, reject) => {
+    timeoutHandle = setTimeout(() => {
+      reject(new Error(`Benchmark timeout after ${adjustedTimeoutMs}ms`));
+    }, adjustedTimeoutMs);
+  });
+
+  // Run the actual benchmark
+  const benchmarkStart = Date.now();
+  let completedIterations = 0;
+  let timedOut = false;
+
+  try {
+    // Run iterations with timeout protection
+    await Promise.race([
+      (async () => {
+        for (let i = 0; i < targetIterations; i++) {
+          await operation();
+          completedIterations++;
+
+          // Check if we're approaching the timeout
+          const elapsed = Date.now() - benchmarkStart;
+          if (elapsed > adjustedTimeoutMs * 0.95) {
+            // Approaching timeout - stopping early
+            break;
+          }
+        }
+      })(),
+      timeoutPromise,
+    ]);
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("timeout")) {
+      timedOut = true;
+      // Benchmark timed out
+    } else {
+      throw error;
+    }
+  } finally {
+    if (timeoutHandle) clearTimeout(timeoutHandle);
+  }
+
+  const totalDuration = Date.now() - benchmarkStart;
+  const avgIterationTime = totalDuration / completedIterations;
+
+  const result: BenchmarkResult = {
+    iterations: completedIterations,
+    totalDurationMs: totalDuration,
+    avgIterationMs: avgIterationTime,
+    timedOut,
+  };
+
+  // Benchmark results debug info removed to prevent console logging issues
+
+  return result;
+}
+
+/**
+ * Helper function to run an operation with adaptive iterations and a callback.
+ * This is useful for tests that need to process results after each iteration.
+ *
+ * @param operation - The async function that returns a value
+ * @param callback - Function to process each result
+ * @param options - Configuration options for the benchmark
+ */
+export async function runAdaptiveBenchmarkWithCallback<T>(
+  operation: () => Promise<T>,
+  callback: (result: T, iteration: number) => void | Promise<void>,
+  options: BenchmarkOptions = {},
+): Promise<BenchmarkResult> {
+  let iterationCount = 0;
+
+  const wrappedOperation = async () => {
+    const result = await operation();
+    await callback(result, iterationCount++);
+  };
+
+  return runAdaptiveBenchmark(wrappedOperation, options);
+}

package/src/test-utils/debuglog-child.ts

@@ -1,13 +1,41 @@
 import { debugLogContext, isDebugEnabled } from "../debuglog";
 
+// Ensure clean process state on Windows
+process.on("uncaughtException", (err) => {
+  const errorMessage = err instanceof Error ? err.message : String(err);
+  process.stderr.write(
+    `Uncaught exception in debuglog-child: ${errorMessage}\n`,
+  );
+  process.exit(1);
+});
+
+process.on("unhandledRejection", (reason) => {
+  const errorMessage =
+    reason instanceof Error ? reason.message : String(reason);
+  process.stderr.write(
+    `Unhandled rejection in debuglog-child: ${errorMessage}\n`,
+  );
+  process.exit(1);
+});
+
 try {
   const result = {
     isDebugEnabled: isDebugEnabled(),
     debugLogContext: debugLogContext(),
   };
-  console.log(JSON.stringify(result));
+  // Use process.stdout.write to ensure clean output
+  process.stdout.write(JSON.stringify(result));
   process.exit(0);
 } catch (err) {
-  console.error(err);
+  // Don't log the error object directly as it might have circular references
+  // that cause issues with Jest's message passing on Windows
+  const errorMessage = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`Error in debuglog-child: ${errorMessage}\n`);
+
+  // Also log stack trace for debugging
+  if (err instanceof Error && err.stack) {
+    process.stderr.write(`Stack trace:\n${err.stack}\n`);
+  }
+
   process.exit(1);
 }

package/src/test-utils/debuglog-enabled-child.ts

@@ -1,10 +1,40 @@
 import { debug } from "../debuglog";
 
-// This will be run with NODE_DEBUG set, so debug should be enabled
-debug("test message %s %d", "hello", 42);
-debug("simple message");
-debug("object %o", { key: "value" });
-
-// Signal successful completion
-console.log("DONE");
-process.exit(0);
+// Ensure clean process state on Windows
+process.on("uncaughtException", (err) => {
+  const errorMessage = err instanceof Error ? err.message : String(err);
+  process.stderr.write(
+    `Uncaught exception in debuglog-enabled-child: ${errorMessage}\n`,
+  );
+  process.exit(1);
+});
+
+process.on("unhandledRejection", (reason) => {
+  const errorMessage =
+    reason instanceof Error ? reason.message : String(reason);
+  process.stderr.write(
+    `Unhandled rejection in debuglog-enabled-child: ${errorMessage}\n`,
+  );
+  process.exit(1);
+});
+
+try {
+  // This will be run with NODE_DEBUG set, so debug should be enabled
+  debug("test message %s %d", "hello", 42);
+  debug("simple message");
+  debug("object %o", { key: "value" });
+
+  // Signal successful completion using stdout.write for clean output
+  process.stdout.write("DONE");
+  process.exit(0);
+} catch (err) {
+  const errorMessage = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`Error in debuglog-enabled-child: ${errorMessage}\n`);
+
+  // Also log stack trace for debugging
+  if (err instanceof Error && err.stack) {
+    process.stderr.write(`Stack trace:\n${err.stack}\n`);
+  }
+
+  process.exit(1);
+}

package/src/test-utils/jest-setup.ts

@@ -0,0 +1,14 @@
+// Jest setup file - runs before all tests
+// Configures global test environment and timeouts
+
+import { jest } from "@jest/globals";
+import { getTestTimeout } from "./test-timeout-config";
+
+// Configure Jest timeout globally for all tests
+jest.setTimeout(getTestTimeout());
+
+// Set consistent timezone for tests (similar to PhotoStructure approach)
+process.env["TZ"] = "America/Los_Angeles";
+
+// Ensure test environment
+process.env["NODE_ENV"] = "test";

package/src/test-utils/memory-test-core.ts

@@ -0,0 +1,336 @@
+import { mkdirSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { env, platform } from "node:process";
+import { delay } from "../async";
+import {
+  getAllVolumeMetadata,
+  getVolumeMetadata,
+  getVolumeMountPoints,
+  isHidden,
+  setHidden,
+} from "../index";
+import { randomLetters } from "../random";
+import { MiB } from "../units";
+import { runAdaptiveBenchmarkWithCallback } from "./benchmark-harness";
+import { getTimingMultiplier } from "./test-timeout-config";
+
+// Core memory testing logic for the standalone memory test runner
+// This module contains all memory leak detection tests, designed to run
+// outside of Jest for more accurate memory measurements and to avoid
+// Jest worker process issues on Windows CI.
+
+// Simple assertion helper
+function assert(condition: boolean, message: string): void {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+// Enable garbage collection access
+declare const global: {
+  gc?: () => void;
+} & typeof globalThis;
+
+// Helper function to get a temporary directory that's not hidden
+function tmpDirNotHidden(): string {
+  const isMacOS = platform === "darwin";
+  const isWindows = platform === "win32";
+
+  const dir = isMacOS
+    ? join(homedir(), "tmp")
+    : isWindows
+      ? join(env["SystemDrive"] ?? "C:\\", "tmp")
+      : "/tmp";
+
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export interface MemoryTestResult {
+  testName: string;
+  passed: boolean;
+  initialMemory: number;
+  finalMemory: number;
+  memoryIncrease: number;
+  slope: number;
+  errorMessage?: string;
+}
+
+// Helper to get memory usage after GC
+async function getMemoryUsage(): Promise<number> {
+  // Give things a bit to fall out of scope
+  // Use dynamic delay based on environment
+  const delayMs = Math.max(10, 100 * getTimingMultiplier());
+  await delay(delayMs);
+  if (global.gc) {
+    global.gc();
+  }
+  await delay(delayMs);
+  return process.memoryUsage().heapUsed;
+}
+
+/**
+ * Detects the likelihood of a memory leak based on memory usage values.
+ * @param memoryUsages - Array of memory usage values.
+ * @returns A boolean indicating if a memory leak is likely.
+ */
+function leastSquaresSlope(memoryUsages: number[]): number {
+  const n = memoryUsages.length;
+  if (n < 2) return 0;
+
+  // Calculate the slope using linear regression (least squares method)
+  const xSum = (n * (n - 1)) / 2;
+  const ySum = memoryUsages.reduce((sum, usage) => sum + usage, 0);
+  const xySum = memoryUsages.reduce((sum, usage, i) => sum + i * usage, 0);
+  const xSquaredSum = (n * (n - 1) * (2 * n - 1)) / 6;
+
+  const result = (n * xySum - xSum * ySum) / (n * xSquaredSum - xSum * xSum);
+
+  // If the slope is positive and significant, it indicates a memory leak
+  return result;
+}
+
+// Helper to check if memory usage is stable
+async function checkMemoryUsage(
+  operation: () => Promise<unknown>,
+  errorMarginBytes: number = 10 * MiB, // Alpine docker had a 5MB variance
+  maxAllowedSlope: number = 0.01,
+): Promise<{
+  passed: boolean;
+  initialMemory: number;
+  finalMemory: number;
+  slope: number;
+  errorMessage?: string;
+}> {
+  // warm up memory consumption:
+  for (let i = 0; i < 5; i++) await operation();
+
+  // __then__ take a snapshot
+  const initialMemory = await getMemoryUsage();
+  const memoryUsages: number[] = [1];
+
+  // Run operations using adaptive benchmark
+  await runAdaptiveBenchmarkWithCallback(
+    operation,
+    async (_result, iteration) => {
+      // Take memory snapshots approximately 10 times during the benchmark
+      // Check every 10 iterations initially, will adjust based on actual runtime
+      if (iteration === 0 || iteration % 10 === 0) {
+        const currentMemory = await getMemoryUsage();
+        memoryUsages.push(currentMemory / initialMemory);
+      }
+    },
+    {
+      targetDurationMs: 10_000, // Reduced from 20s to 10s for faster CI
+      maxTimeoutMs: 30_000, // Reduced from 60s to 30s
+      minIterations: 10,
+      debug: !!process.env["DEBUG_BENCHMARK"],
+    },
+  );
+
+  // Final memory check
+  const finalMemory = await getMemoryUsage();
+  memoryUsages.push(finalMemory / initialMemory);
+  const slope = leastSquaresSlope(memoryUsages);
+
+  const memoryIncrease = finalMemory - initialMemory;
+  let errorMessage: string | undefined;
+
+  if (memoryIncrease >= errorMarginBytes) {
+    errorMessage = `Memory increased by ${(memoryIncrease / MiB).toFixed(2)} MiB, exceeding limit of ${(errorMarginBytes / MiB).toFixed(2)} MiB`;
+  } else if (slope >= maxAllowedSlope) {
+    errorMessage = `Memory slope ${slope.toFixed(4)} exceeds limit of ${maxAllowedSlope}`;
+  }
+
+  return {
+    passed: !errorMessage,
+    initialMemory,
+    finalMemory,
+    slope,
+    ...(errorMessage && { errorMessage }),
+  };
+}
+
+// Memory test implementations
+export async function testVolumeMountPointsNoLeak(): Promise<MemoryTestResult> {
+  const result = await checkMemoryUsage(async () => {
+    const mountPoints = await getVolumeMountPoints();
+    if (mountPoints.length === 0) {
+      throw new Error("Expected at least one mount point");
+    }
+  });
+
+  return {
+    testName: "getVolumeMountPoints - no memory leak",
+    passed: result.passed,
+    initialMemory: result.initialMemory,
+    finalMemory: result.finalMemory,
+    memoryIncrease: result.finalMemory - result.initialMemory,
+    slope: result.slope,
+    ...(result.errorMessage && { errorMessage: result.errorMessage }),
+  };
+}
+
+export async function testVolumeMountPointsErrorConditions(): Promise<MemoryTestResult> {
+  const result = await checkMemoryUsage(async () => {
+    try {
+      await getVolumeMountPoints({ timeoutMs: 1 });
+    } catch {
+      // Expected
+    }
+  });
+
+  return {
+    testName: "getVolumeMountPoints - error conditions",
+    passed: result.passed,
+    initialMemory: result.initialMemory,
+    finalMemory: result.finalMemory,
+    memoryIncrease: result.finalMemory - result.initialMemory,
+    slope: result.slope,
+    ...(result.errorMessage && { errorMessage: result.errorMessage }),
+  };
+}
+
+export async function testGetAllVolumeMetadataNoLeak(): Promise<MemoryTestResult> {
+  const result = await checkMemoryUsage(async () => {
+    const metadata = await getAllVolumeMetadata();
+    if (metadata.length === 0) {
+      throw new Error("Expected at least one volume");
+    }
+  });
+
+  return {
+    testName: "getAllVolumeMetadata - no memory leak",
+    passed: result.passed,
+    initialMemory: result.initialMemory,
+    finalMemory: result.finalMemory,
+    memoryIncrease: result.finalMemory - result.initialMemory,
+    slope: result.slope,
+    ...(result.errorMessage && { errorMessage: result.errorMessage }),
+  };
+}
+
+export async function testGetVolumeMetadataErrorConditions(): Promise<MemoryTestResult> {
+  const result = await checkMemoryUsage(async () => {
+    try {
+      await getVolumeMetadata("nonexistent");
+    } catch {
+      // Expected
+    }
+  });
+
+  return {
+    testName: "getVolumeMetadata - error conditions",
+    passed: result.passed,
+    initialMemory: result.initialMemory,
+    finalMemory: result.finalMemory,
+    memoryIncrease: result.finalMemory - result.initialMemory,
+    slope: result.slope,
+    ...(result.errorMessage && { errorMessage: result.errorMessage }),
+  };
+}
+
+export async function testIsHiddenSetHiddenNoLeak(): Promise<MemoryTestResult> {
+  const testDir = await mkdtemp(join(tmpDirNotHidden(), "memory-tests-"));
+  let counter = 0;
+
+  try {
+    const result = await checkMemoryUsage(async () => {
+      // Create a unique subdirectory for each iteration to avoid path conflicts
+      const iterationDir = join(testDir, `iteration-${counter++}`);
+
+      // Simple validateHidden implementation without Jest dependencies
+      mkdirSync(iterationDir, { recursive: true });
+
+      // Test isHidden on a regular directory (should be false)
+      const isHiddenResult = await isHidden(iterationDir);
+      assert(
+        isHiddenResult === false,
+        `Expected ${iterationDir} to not be hidden`,
+      );
+
+      // Test setHidden to true
+      // On Linux, setHidden renames the file/dir by adding a dot prefix,
+      // so we need to capture the returned pathname
+      const hiddenPath = (await setHidden(iterationDir, true)).pathname;
+      const isHiddenAfterSet = await isHidden(hiddenPath);
+      assert(
+        isHiddenAfterSet === true,
+        `Expected ${hiddenPath} to be hidden after setHidden(true)`,
+      );
+
+      // Test setHidden to false
+      const visiblePath = (await setHidden(hiddenPath, false)).pathname;
+      const isHiddenAfterUnset = await isHidden(visiblePath);
+      assert(
+        isHiddenAfterUnset === false,
+        `Expected ${visiblePath} to not be hidden after setHidden(false)`,
+      );
+    });
+
+    return {
+      testName: "isHidden/setHidden - no memory leak",
+      passed: result.passed,
+      initialMemory: result.initialMemory,
+      finalMemory: result.finalMemory,
+      memoryIncrease: result.finalMemory - result.initialMemory,
+      slope: result.slope,
+      ...(result.errorMessage && { errorMessage: result.errorMessage }),
+    };
+  } finally {
+    await rm(testDir, { recursive: true, force: true }).catch(() => null);
+  }
+}
+
+export async function testIsHiddenSetHiddenErrorConditions(): Promise<MemoryTestResult> {
+  const testDir = await mkdtemp(join(tmpDirNotHidden(), "memory-tests-"));
+
+  try {
+    const result = await checkMemoryUsage(async () => {
+      const notafile = join(testDir, "nonexistent", "file-" + randomLetters(8));
+      try {
+        await isHidden(notafile);
+      } catch {
+        // Expected
+      }
+      try {
+        await setHidden(notafile, true);
+      } catch {
+        // Expected
+      }
+    });
+
+    return {
+      testName: "isHidden/setHidden - error conditions",
+      passed: result.passed,
+      initialMemory: result.initialMemory,
+      finalMemory: result.finalMemory,
+      memoryIncrease: result.finalMemory - result.initialMemory,
+      slope: result.slope,
+      ...(result.errorMessage && { errorMessage: result.errorMessage }),
+    };
+  } finally {
+    await rm(testDir, { recursive: true, force: true }).catch(() => null);
+  }
+}
+
+// Run all memory tests
+export async function runAllMemoryTests(): Promise<MemoryTestResult[]> {
+  if (!global.gc) {
+    throw new Error("Garbage collection must be exposed. Run with --expose-gc");
+  }
+
+  const results: MemoryTestResult[] = [];
+
+  // Run each test and collect results
+  results.push(await testVolumeMountPointsNoLeak());
+  results.push(await testVolumeMountPointsErrorConditions());
+  results.push(await testGetAllVolumeMetadataNoLeak());
+  results.push(await testGetVolumeMetadataErrorConditions());
+  results.push(await testIsHiddenSetHiddenNoLeak());
+  results.push(await testIsHiddenSetHiddenErrorConditions());
+
+  return results;
+}