@photostructure/fs-metadata 0.4.0 → 0.5.0

package/scripts/check-memory.mjs

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+/**
+ * Cross-platform memory checking script
+ * Runs JavaScript memory tests on all platforms
+ * Runs valgrind and ASAN tests only on Linux
+ */
+
+import { execSync } from "child_process";
+import { writeFileSync } from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Colors for output
+const colors = {
+  RED: "\x1b[31m",
+  GREEN: "\x1b[32m",
+  YELLOW: "\x1b[33m",
+  BLUE: "\x1b[34m",
+  RESET: "\x1b[0m",
+};
+
+// Use colors only if not on Windows
+const isWindows = os.platform() === "win32";
+const color = (colorCode, text) =>
+  isWindows ? text : `${colorCode}${text}${colors.RESET}`;
+
+console.log(color(colors.BLUE, "=== Memory Leak Detection Suite ==="));
+
+let exitCode = 0;
+
+// 1. Run JavaScript memory tests (all platforms)
+console.log(color(colors.YELLOW, "\nRunning JavaScript memory tests..."));
+try {
+  execSync("npm run test:memory", { stdio: "inherit" });
+  console.log(color(colors.GREEN, "✓ JavaScript memory tests passed"));
+} catch {
+  console.log(color(colors.RED, "✗ JavaScript memory tests failed"));
+  exitCode = 1;
+}
+
+// 2. Run valgrind if available and on Linux
+if (os.platform() === "linux") {
+  try {
+    execSync("which valgrind", { stdio: "ignore" });
+    console.log(color(colors.YELLOW, "\nRunning valgrind memory analysis..."));
+    try {
+      const valgrindScript = path.join(__dirname, "valgrind.sh");
+      execSync(valgrindScript, { stdio: "inherit" });
+      console.log(color(colors.GREEN, "✓ Valgrind tests passed"));
+    } catch {
+      console.log(color(colors.RED, "✗ Valgrind tests failed"));
+      exitCode = 1;
+    }
+  } catch {
+    console.log(color(colors.YELLOW, "\nValgrind not available. Skipping."));
+  }
+} else {
+  console.log(
+    color(colors.YELLOW, "\nValgrind tests only run on Linux. Skipping."),
+  );
+}
+
+// 3. Run Address Sanitizer if requested (Linux only for now)
+if (process.env.ENABLE_ASAN) {
+  if (os.platform() === "linux") {
+    console.log(color(colors.YELLOW, "\nBuilding with AddressSanitizer..."));
+    try {
+      // Check if clang is available
+      execSync("which clang", { stdio: "ignore" });
+
+      const env = {
+        ...process.env,
+        CC: "clang",
+        CXX: "clang++",
+        CFLAGS: "-fsanitize=address -fno-omit-frame-pointer -g -O1",
+        CXXFLAGS: "-fsanitize=address -fno-omit-frame-pointer -g -O1",
+        LDFLAGS: "-fsanitize=address",
+        ASAN_OPTIONS: "detect_leaks=1:halt_on_error=0:print_stats=1",
+        LSAN_OPTIONS: `suppressions=${path.join(process.cwd(), ".lsan-suppressions.txt")}:print_suppressions=0`,
+      };
+
+      // Find ASan runtime library using clang
+      try {
+        const asanLib = execSync(
+          "clang -print-file-name=libclang_rt.asan-x86_64.so",
+          { encoding: "utf8" },
+        ).trim();
+        if (asanLib && !asanLib.includes("not found")) {
+          env.LD_PRELOAD = asanLib;
+          console.log(color(colors.BLUE, `Using ASan library: ${asanLib}`));
+        }
+      } catch {
+        // Try common paths as fallback
+        const asanLibPaths = [
+          "/usr/lib/x86_64-linux-gnu/libasan.so.8",
+          "/usr/lib/x86_64-linux-gnu/libasan.so.6",
+          "/usr/lib64/libasan.so.8",
+          "/usr/lib64/libasan.so.6",
+        ];
+
+        for (const libPath of asanLibPaths) {
+          try {
+            execSync(`test -f ${libPath}`, { stdio: "ignore" });
+            env.LD_PRELOAD = libPath;
+            console.log(color(colors.BLUE, `Using ASan library: ${libPath}`));
+            break;
+          } catch {
+            // Try next path
+          }
+        }
+      }
+
+      execSync("npm run node-gyp-rebuild", { stdio: "inherit", env });
+
+      console.log(
+        color(colors.YELLOW, "Running tests with AddressSanitizer..."),
+      );
+
+      // Capture ASAN output for analysis
+      let asanOutput = "";
+      try {
+        asanOutput = execSync("npm test -- --no-coverage 2>&1", {
+          env,
+        }).toString();
+        console.log(asanOutput);
+      } catch (error) {
+        asanOutput = error.stdout ? error.stdout.toString() : "";
+        asanOutput += error.stderr ? error.stderr.toString() : "";
+        console.log(asanOutput);
+      }
+
+      // Save full output to file
+      const outputFile = path.join(process.cwd(), "asan-output.log");
+      writeFileSync(outputFile, asanOutput);
+      console.log(
+        color(colors.BLUE, `\nFull ASAN output saved to: ${outputFile}`),
+      );
+
+      // Check for ASAN errors in our code (not V8/Node internals)
+      const lines = asanOutput.split("\n");
+      const hasOurErrors = lines.some(
+        (line) =>
+          (line.includes("ERROR: AddressSanitizer") ||
+            line.includes("ERROR: LeakSanitizer")) &&
+          (line.includes("fs_metadata.node") || line.includes("/src/")),
+      );
+
+      const hasOurLeaks = lines.some(
+        (line) =>
+          (line.includes("Direct leak") || line.includes("Indirect leak")) &&
+          lines
+            .slice(
+              Math.max(0, lines.indexOf(line) - 5),
+              lines.indexOf(line) + 10,
+            )
+            .some(
+              (context) =>
+                context.includes("fs_metadata.node") ||
+                context.includes("/src/"),
+            ),
+      );
+
+      // Count V8/Node internal leaks for information
+      const internalLeaks = (asanOutput.match(/leak.*\/usr\/bin\/node/g) || [])
+        .length;
+
+      if (hasOurErrors || hasOurLeaks) {
+        console.log(
+          color(
+            colors.RED,
+            "\n✗ AddressSanitizer found issues in fs-metadata code:",
+          ),
+        );
+
+        // Extract relevant error lines
+        const relevantErrors = lines.filter((line, idx) => {
+          if (line.includes("ERROR:") || line.includes("leak")) {
+            // Check context around this line for our code
+            const context = lines
+              .slice(Math.max(0, idx - 5), idx + 10)
+              .join("\n");
+            return (
+              context.includes("fs_metadata.node") || context.includes("/src/")
+            );
+          }
+          return false;
+        });
+
+        relevantErrors.forEach((line) => console.log(color(colors.RED, line)));
+        exitCode = 1;
+      } else {
+        console.log(
+          color(
+            colors.GREEN,
+            "✓ AddressSanitizer tests passed (no issues in fs-metadata code)",
+          ),
+        );
+        if (internalLeaks > 0) {
+          console.log(
+            color(
+              colors.YELLOW,
+              `   Note: ${internalLeaks} V8/Node.js internal leaks detected (suppressed)`,
+            ),
+          );
+        }
+      }
+    } catch (error) {
+      if (error && error.code === 1) {
+        console.log(
+          color(
+            colors.YELLOW,
+            "clang not found. Skipping AddressSanitizer tests.",
+          ),
+        );
+      } else {
+        console.log(color(colors.RED, "✗ AddressSanitizer tests failed"));
+        exitCode = 1;
+      }
+    }
+  } else {
+    console.log(
+      color(
+        colors.YELLOW,
+        "\nAddressSanitizer tests are currently only supported on Linux. Skipping.",
+      ),
+    );
+  }
+}
+
+if (exitCode === 0) {
+  console.log(
+    color(colors.GREEN, "\n=== All memory tests completed successfully! ==="),
+  );
+} else {
+  console.log(color(colors.RED, "\n=== Some memory tests failed ==="));
+}
+
+process.exit(exitCode);

package/scripts/clang-tidy.mjs

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+import { execSync, spawn } from "child_process";
+import { platform } from "os";
+
+// Skip clang-tidy on Windows
+if (platform() === "win32") {
+  console.log("Skipping clang-tidy on Windows platform");
+  process.exit(0);
+}
+
+// Check for required tools
+function checkCommand(command, installHint) {
+  try {
+    execSync(`which ${command}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    console.error(`Error: '${command}' not found in PATH.`);
+    console.error(`To install: ${installHint}`);
+    return false;
+  }
+}
+
+const isMacOS = platform() === "darwin";
+const isLinux = platform() === "linux";
+
+let hasAllTools = true;
+
+if (
+  !checkCommand(
+    "bear",
+    isLinux
+      ? "sudo apt-get install bear"
+      : isMacOS
+        ? "brew install bear"
+        : "see https://github.com/rizsotto/Bear",
+  )
+) {
+  hasAllTools = false;
+}
+
+if (
+  !checkCommand(
+    "clang-tidy",
+    isLinux
+      ? "sudo apt-get install clang-tidy"
+      : isMacOS
+        ? "brew install llvm && alias clang-tidy=$(brew --prefix llvm)/bin/clang-tidy"
+        : "see https://clang.llvm.org/extra/clang-tidy/",
+  )
+) {
+  hasAllTools = false;
+}
+
+if (!hasAllTools) {
+  process.exit(1);
+}
+
+// Run the clang-tidy command on Unix platforms
+const command = `npm run configure && bear -- npm run node-gyp-rebuild && find src -name '*.cpp' -o -name '*.h' | grep -E '\\.(cpp|h)$' | grep -v -E '(windows|darwin)/' | xargs clang-tidy`;
+
+const shell = spawn("sh", ["-c", command], {
+  stdio: "inherit",
+  shell: false,
+});
+
+shell.on("exit", (code) => {
+  process.exit(code || 0);
+});
+
+shell.on("error", (err) => {
+  console.error("Failed to run clang-tidy:", err);
+  process.exit(1);
+});

package/scripts/is-platform.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { platform } from "os";
+
+const targetPlatform = process.argv[2];
+if (!targetPlatform) {
+  console.error("Usage: is-platform.mjs <platform>");
+  console.error("Example: is-platform.mjs win32");
+  process.exit(2);
+}
+
+// Exit with 0 if current platform matches target, 1 otherwise
+process.exit(platform() === targetPlatform ? 0 : 1);

package/scripts/post-build.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+
+import { copyFile } from "fs/promises";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distDir = join(__dirname, "..", "dist");
+
+// Copy .d.ts to .d.cts for CommonJS type safety
+async function createCjsTypes() {
+  try {
+    await copyFile(join(distDir, "index.d.ts"), join(distDir, "index.d.cts"));
+    console.log("Created index.d.cts for CommonJS type safety");
+  } catch (error) {
+    console.error("Error creating .d.cts file:", error);
+    process.exit(1);
+  }
+}
+
+createCjsTypes();

package/scripts/run-asan.sh

@@ -0,0 +1,92 @@
+#!/bin/bash
+# AddressSanitizer test runner for @photostructure/fs-metadata
+
+set -euo pipefail
+
+# Check if we're on Linux
+if [[ "$OSTYPE" != "linux-gnu"* ]]; then
+    echo "AddressSanitizer tests are only supported on Linux"
+    exit 0
+fi
+
+# Check for clang
+if ! command -v clang &> /dev/null; then
+    echo "Error: clang is required for AddressSanitizer tests"
+    echo "Install with: sudo apt-get install clang"
+    exit 1
+fi
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+echo -e "${YELLOW}Running AddressSanitizer tests...${NC}"
+
+# Clean previous builds
+echo "Cleaning previous builds..."
+rm -rf build/
+rm -f asan-output.log
+
+# Set up ASan environment
+export CC=clang
+export CXX=clang++
+export CFLAGS="-fsanitize=address -fno-omit-frame-pointer -g -O1"
+export CXXFLAGS="-fsanitize=address -fno-omit-frame-pointer -g -O1"
+export LDFLAGS="-fsanitize=address"
+
+# Find ASan runtime library
+ASAN_LIB=$(clang -print-file-name=libclang_rt.asan-x86_64.so 2>/dev/null || true)
+if [[ -f "$ASAN_LIB" ]]; then
+    export LD_PRELOAD="$ASAN_LIB"
+    echo "Using ASan library: $ASAN_LIB"
+fi
+
+# Set ASan options
+export ASAN_OPTIONS="detect_leaks=1:check_initialization_order=1:strict_init_order=1:print_stats=1:print_module_map=1"
+export LSAN_OPTIONS="suppressions=$(pwd)/.lsan-suppressions.txt:print_suppressions=0"
+
+# Set Node.js options to increase memory for ASan overhead
+export NODE_OPTIONS="--max-old-space-size=8192"
+
+# Build the native module
+echo "Building with AddressSanitizer..."
+npm run node-gyp-rebuild
+
+# Run tests and capture output
+echo "Running tests..."
+npm run test -- --no-coverage 2>&1 | tee asan-output.log
+
+# Analyze results
+echo -e "\n${YELLOW}Analyzing AddressSanitizer output...${NC}"
+
+# Check for errors in our code (excluding V8/Node internals)
+if grep -E "ERROR: AddressSanitizer" asan-output.log | grep -v "/usr/bin/node" > /dev/null 2>&1; then
+    echo -e "${RED}AddressSanitizer detected errors in fs-metadata code!${NC}"
+    grep -A5 -B5 "ERROR: AddressSanitizer" asan-output.log | grep -v "/usr/bin/node" || true
+    exit 1
+fi
+
+# Check for leaks in our code
+if grep -E "Direct leak.*photostructure|Indirect leak.*photostructure" asan-output.log > /dev/null 2>&1; then
+    echo -e "${RED}Memory leaks detected in fs-metadata code!${NC}"
+    grep -A5 -B5 "leak.*photostructure" asan-output.log || true
+    exit 1
+fi
+
+# Check for any leaks from our native module
+if grep -E "leak.*build/Release/fs_metadata.node" asan-output.log > /dev/null 2>&1; then
+    echo -e "${RED}Memory leaks detected in native module!${NC}"
+    grep -A5 -B5 "leak.*fs_metadata.node" asan-output.log || true
+    exit 1
+fi
+
+# Report on V8/Node.js internal leaks (informational only)
+INTERNAL_LEAKS=$(grep -c "leak.*node" asan-output.log 2>/dev/null || echo "0")
+if [[ "$INTERNAL_LEAKS" -gt 0 ]]; then
+    echo -e "${YELLOW}Note: Found $INTERNAL_LEAKS V8/Node.js internal leaks (suppressed)${NC}"
+fi
+
+echo -e "${GREEN}✓ AddressSanitizer tests passed! No memory errors in fs-metadata code.${NC}"
+echo "Full output saved to: asan-output.log"

package/scripts/valgrind-test.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+/**
+ * Valgrind test runner for @photostructure/fs-metadata
+ *
+ * This script exercises the native module's core functionality to detect
+ * memory leaks. It's designed to be run under valgrind via npm run test:valgrind
+ *
+ * The test performs multiple iterations of each operation to help detect
+ * memory leaks that might only appear after repeated use.
+ */
+
+import {
+  getAllVolumeMetadata,
+  getVolumeMetadata,
+  getVolumeMountPoints,
+  isHidden,
+} from "../dist/index.js";
+
+async function runTests() {
+  console.log("Starting valgrind memory leak tests...");
+
+  // Test 1: Exercise getVolumeMountPoints multiple times
+  console.log("Test 1: getVolumeMountPoints");
+  for (let i = 0; i < 10; i++) {
+    await getVolumeMountPoints();
+    if (i % 5 === 0) console.log(`  Iteration ${i + 1}/10`);
+  }
+
+  // Test 2: Exercise getVolumeMetadata with valid and invalid paths
+  console.log("Test 2: getVolumeMetadata");
+  for (let i = 0; i < 10; i++) {
+    try {
+      await getVolumeMetadata("/");
+    } catch {
+      // Expected for some platforms
+    }
+
+    try {
+      await getVolumeMetadata("/nonexistent-path-" + i);
+    } catch {
+      // Expected - testing error paths
+    }
+
+    if (i % 5 === 0) console.log(`  Iteration ${i + 1}/10`);
+  }
+
+  // Test 3: Exercise getAllVolumeMetadata
+  console.log("Test 3: getAllVolumeMetadata");
+  try {
+    await getAllVolumeMetadata();
+    console.log("  Completed successfully");
+  } catch (e) {
+    console.log("  Completed with expected error:", e.message);
+  }
+
+  // Test 4: Exercise hidden file operations
+  console.log("Test 4: isHidden");
+  const testPaths = ["/tmp", "/var", "/nonexistent"];
+  for (let i = 0; i < 10; i++) {
+    for (const path of testPaths) {
+      try {
+        await isHidden(path);
+      } catch {
+        // Expected for some paths
+      }
+    }
+    if (i % 5 === 0) console.log(`  Iteration ${i + 1}/10`);
+  }
+
+  console.log("Valgrind tests completed");
+}
+
+// Run tests and exit
+runTests()
+  .then(() => {
+    console.log("All tests completed successfully");
+    process.exit(0);
+  })
+  .catch((err) => {
+    console.error("Test error:", err);
+    process.exit(1);
+  });

package/scripts/valgrind.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+
+# Valgrind memory leak detection script for CI/CD
+set -e
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+ROOT_DIR="$(dirname "$SCRIPT_DIR")"
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Check if valgrind is available
+if ! command -v valgrind &> /dev/null; then
+    echo -e "${YELLOW}Warning: valgrind not found. Skipping memory leak tests.${NC}"
+    exit 0
+fi
+
+# Only run on Linux
+if [[ "$OSTYPE" != "linux-gnu"* ]]; then
+    echo -e "${YELLOW}Valgrind tests only run on Linux. Skipping.${NC}"
+    exit 0
+fi
+
+echo -e "${GREEN}Running valgrind memory leak detection...${NC}"
+
+# Path to the dedicated valgrind test script
+VALGRIND_TEST="$SCRIPT_DIR/valgrind-test.mjs"
+
+# Ensure the test script exists
+if [ ! -f "$VALGRIND_TEST" ]; then
+    echo -e "${RED}Error: Valgrind test script not found at $VALGRIND_TEST${NC}"
+    exit 1
+fi
+
+# Use the committed suppressions file
+SUPP_FILE="$ROOT_DIR/.valgrind.supp"
+
+# Ensure suppressions file exists
+if [ ! -f "$SUPP_FILE" ]; then
+    echo -e "${RED}Error: Valgrind suppressions file not found at $SUPP_FILE${NC}"
+    exit 1
+fi
+
+# Run valgrind with appropriate options
+VALGRIND_OPTS="--leak-check=full --show-leak-kinds=definite,indirect,possible --track-origins=yes --suppressions=$SUPP_FILE"
+
+echo "Running valgrind tests..."
+if valgrind $VALGRIND_OPTS node "$VALGRIND_TEST" 2>&1 | tee "$ROOT_DIR/valgrind.log"; then
+    # Check the log for actual leaks
+    if grep -q "definitely lost: 0 bytes in 0 blocks" "$ROOT_DIR/valgrind.log" && \
+       grep -q "indirectly lost: 0 bytes in 0 blocks" "$ROOT_DIR/valgrind.log"; then
+        echo -e "${GREEN}✓ No memory leaks detected${NC}"
+        RESULT=0
+    else
+        echo -e "${RED}✗ Memory leaks detected${NC}"
+        grep -A 5 "LEAK SUMMARY" "$ROOT_DIR/valgrind.log"
+        RESULT=1
+    fi
+else
+    echo -e "${RED}✗ Valgrind error${NC}"
+    RESULT=1
+fi
+
+# Cleanup log file only (keep the committed suppression file)
+rm -f "$ROOT_DIR/valgrind.log"
+
+exit $RESULT

package/src/async.ts

@@ -1,8 +1,8 @@
 import { availableParallelism } from "node:os";
 import { env } from "node:process";
-import { gt0, isNumber } from "./number.js";
-import { isBlank } from "./string.js";
-import { DayMs } from "./units.js";
+import { gt0, isNumber } from "./number";
+import { isBlank } from "./string";
+import { DayMs } from "./units";
 
 /**
  * An error that is thrown when a promise does not resolve within the specified

package/src/binding.cpp

@@ -20,7 +20,7 @@
 namespace {
 
 Napi::Value SetDebugLogging(const Napi::CallbackInfo &info) {
-  Napi::Env env = info.Env();
+  const Napi::Env env = info.Env();
 
   if (info.Length() < 1 || !info[0].IsBoolean()) {
     throw Napi::TypeError::New(env, "Boolean argument expected");
@@ -31,7 +31,7 @@ Napi::Value SetDebugLogging(const Napi::CallbackInfo &info) {
 }
 
 Napi::Value SetDebugPrefix(const Napi::CallbackInfo &info) {
-  Napi::Env env = info.Env();
+  const Napi::Env env = info.Env();
 
   if (info.Length() < 1 || !info[0].IsString()) {
     throw Napi::TypeError::New(env, "String argument expected");
@@ -44,7 +44,7 @@ Napi::Value SetDebugPrefix(const Napi::CallbackInfo &info) {
 
 #ifdef ENABLE_GIO
 Napi::Value GetGioMountPoints(const Napi::CallbackInfo &info) {
-  Napi::Env env = info.Env();
+  const Napi::Env env = info.Env();
   return FSMeta::gio::GetMountPoints(env);
 }
 #endif

package/src/error.ts

@@ -1,8 +1,8 @@
 // src/error.ts
 
-import { isNumber } from "./number.js";
-import { compactValues, map, omit } from "./object.js";
-import { isBlank, isNotBlank } from "./string.js";
+import { isNumber } from "./number";
+import { compactValues, map, omit } from "./object";
+import { isBlank, isNotBlank } from "./string";
 
 function toMessage(context: string, cause: unknown): string {
   const causeStr =

package/src/fs.ts

@@ -3,7 +3,7 @@
 import { type PathLike, type StatOptions, Stats, statSync } from "node:fs";
 import { opendir, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
-import { withTimeout } from "./async.js";
+import { withTimeout } from "./async";
 
 /**
  * Wrapping node:fs/promises.stat() so we can mock it in tests.

package/src/glob.ts

@@ -1,7 +1,7 @@
 // src/glob.ts
 
-import { isWindows } from "./platform.js";
-import { isNotBlank } from "./string.js";
+import { isWindows } from "./platform";
+import { isNotBlank } from "./string";
 
 const cache = new Map<string, RegExp>();
 

package/src/hidden.ts

@@ -2,12 +2,12 @@
 
 import { rename } from "node:fs/promises";
 import { basename, dirname, join } from "node:path";
-import { WrappedError } from "./error.js";
-import { canStatAsync, statAsync } from "./fs.js";
-import { isRootDirectory, normalizePath } from "./path.js";
-import { isWindows } from "./platform.js";
-import type { HiddenMetadata } from "./types/hidden_metadata.js";
-import type { NativeBindingsFn } from "./types/native_bindings.js";
+import { WrappedError } from "./error";
+import { canStatAsync, statAsync } from "./fs";
+import { isRootDirectory, normalizePath } from "./path";
+import { isWindows } from "./platform";
+import type { HiddenMetadata } from "./types/hidden_metadata";
+import type { NativeBindingsFn } from "./types/native_bindings";
 
 const HiddenSupportByPlatform: Partial<
   Record<NodeJS.Platform, Pick<HiddenMetadata, "supported">>