@photostructure/fs-metadata 1.2.0 → 1.4.0

package/doc/C++_REVIEW_TODO.md

@@ -142,12 +142,10 @@ This document outlines a comprehensive review of all C++ files in the fs-metadat
 
 - [x] Review BlkidCache RAII wrapper - Already excellent
 - [x] Check blkid_get_tag_value free() calls - Correctly using free()
-- [x] Verify GIO integration memory management - Proper smart pointers
 - [x] Validate statvfs error handling - Already comprehensive
 - [x] **Added**: Input validation for empty mount points
 - **Platform APIs verified**:
   - libblkid API availability
-  - GIO optional dependency handling
   - statvfs behavior
 
 #### `src/linux/blkid_cache.cpp` ✅
@@ -159,38 +157,8 @@ This document outlines a comprehensive review of all C++ files in the fs-metadat
 - **Platform APIs verified**:
   - libblkid cache APIs - Proper use of blkid_get_cache/blkid_put_cache
 
-#### `src/linux/gio_utils.cpp` (if GIO enabled) ✅
-
-- [x] Review g_object_unref patterns - Already using GioResource RAII
-- [x] Check GError cleanup - Not used in this file (GError-free patterns)
-- [x] Verify GMount/GVolume reference counting - Proper ref/unref pairs
-- [x] **Added**: Exception handling in forEachMount callback
-- [x] **Added**: Null checks for root.get() before G_IS_FILE
-- [x] **Added**: const-correctness for GioResource and callback results
-- **Platform APIs verified**:
-  - GLib/GIO APIs (GNOME) - Proper memory management patterns
-  - GVfs mount integration
-
-#### `src/linux/gio_mount_points.cpp` (if GIO enabled) ✅
-
-- [x] Review g_volume_monitor lifecycle - Correct usage (singleton pattern)
-- [x] Check GList cleanup patterns - Using g_list_free_full correctly
-- [x] Verify string ownership - Proper GCharPtr smart pointers
-- [x] **Added**: const-correctness for local variables (GCharPtr, GFileInfoPtr, etc.)
-- **Platform APIs verified**:
-  - GVolumeMonitor APIs - Reference counting rules
-  - Mount enumeration
-
-#### `src/linux/gio_volume_metadata.cpp` (if GIO enabled) ✅
-
-- [x] Review g_drive object management - Using GObjectPtr smart pointers
-- [x] Check g_icon handling - No GIcon usage in this file
-- [x] Verify string ownership - Proper GCharPtr usage
-- [x] **Added**: Defensive null checks for GObjectPtr::get()
-- [x] **Added**: Null checks for string getters
-- [x] **Added**: const-correctness for all GCharPtr and GObjectPtr locals
-- **Platform APIs verified**:
-  - GDrive/GVolume metadata APIs - Ownership transfer rules
+> **Note**: GIO/GLib integration was removed in favor of `/proc/self/mounts`
+> parsing in TypeScript. See CHANGELOG.md for details.
 
 ## Testing Strategy
 
@@ -237,7 +205,7 @@ This document outlines a comprehensive review of all C++ files in the fs-metadat
    - ✅ WNetConnection: Handle ERROR_MORE_DATA with dynamic buffer resize
    - ✅ GetVolumeInformation: Use MAX_PATH+1 instead of BUFFER_SIZE
 3. ~~**High**: CoreFoundation reference counting in macOS code~~ ✅ Completed - CFReleaser RAII wrapper
-4. ~~**High**: GIO object lifecycle management~~ ✅ Completed - Using smart pointers throughout
+4. ~~**High**: GIO object lifecycle management~~ ✅ N/A - GIO integration removed entirely (see CHANGELOG)
 5. ~~**Medium**: Security - Add comprehensive path validation~~ ✅ Completed
    - ✅ Check for ".." in all platforms (Windows/Darwin have it, Linux doesn't have hidden file support)
    - Validate against null bytes and special characters (remaining)
@@ -358,6 +326,5 @@ The Darwin/macOS implementation demonstrates excellent resource management with
 ### Linux
 
 - libblkid: Use free() for blkid_get_tag_value results, blkid_put_cache() for cache
-- GLib/GIO: Use g_object_unref() or g_clear_object(), match allocation functions
 - Key Documentation: libblkid man pages, GNOME Developer Documentation
 - **Review Status**: ✅ All files properly reviewed and use smart pointers

package/doc/LINUX_API_REFERENCE.md

@@ -4,115 +4,10 @@ Reference for Linux APIs used in fs-metadata, with links to official documentati
 
 ## Table of Contents
 
-1. [GIO/GLib APIs](#gioglib-apis)
-2. [libblkid APIs](#libblkid-apis)
-3. [POSIX File System APIs](#posix-file-system-apis)
-4. [RAII Patterns](#raii-patterns)
-5. [References](#references)
-
-## GIO/GLib APIs
-
-### Thread Safety Overview
-
-**Critical**: GIO has different thread safety guarantees for different APIs:
-
-| API                      | Thread Safe? | Used? | Notes                                     |
-| ------------------------ | ------------ | ----- | ----------------------------------------- |
-| `g_unix_mounts_get()`    | Yes          | ✅    | Uses `getmntent_r()` or internal `G_LOCK` |
-| `g_unix_mount_get_*()`   | Yes          | ✅    | Safe on `GUnixMountEntry`                 |
-| `g_volume_monitor_get()` | **No**       | ❌    | Main thread only - **NOT USED**           |
-
-**GIO Threading Docs**: https://docs.gtk.org/gio/class.VolumeMonitor.html
-
-> "GVolumeMonitor is not thread-default-context aware and should not be used other than from the main thread."
-
-This codebase only uses thread-safe APIs (`g_unix_mounts_get()` and related functions)
-because all native code runs on `Napi::AsyncWorker` threads.
-
-### g_unix_mounts_get
-
-- **Docs**: https://docs.gtk.org/gio/func.unix_mounts_get.html
-- **Purpose**: Thread-safe enumeration of mounted filesystems
-- **Returns**: `GList*` of `GUnixMountEntry*` (caller owns both)
-- **Cleanup**: `g_list_free_full(list, (GDestroyNotify)g_unix_mount_free)`
-
-```cpp
-GList *mounts = g_unix_mounts_get(nullptr);
-for (GList *l = mounts; l != nullptr; l = l->next) {
-    GUnixMountEntry *entry = static_cast<GUnixMountEntry*>(l->data);
-    const char *path = g_unix_mount_get_mount_path(entry);
-    const char *fstype = g_unix_mount_get_fs_type(entry);
-}
-g_list_free_full(mounts, reinterpret_cast<GDestroyNotify>(g_unix_mount_free));
-```
-
-**Source**: https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gunixmounts.c
-
-### GUnixMountEntry Functions
-
-- **Docs**: https://docs.gtk.org/gio-unix/struct.MountEntry.html
-- `g_unix_mount_get_mount_path()` - Returns `const char*` (borrowed)
-- `g_unix_mount_get_fs_type()` - Returns `const char*` (borrowed)
-- `g_unix_mount_get_device_path()` - Returns `const char*` (borrowed)
-- `g_unix_mount_free()` - Free a single entry
-
-**Note**: String returns are borrowed - do NOT `g_free()` them.
-
-### g_volume_monitor_get (NOT USED)
-
-> ⚠️ **NOT USED IN THIS CODEBASE**: GVolumeMonitor is NOT thread-safe and has been
-> removed from fs-metadata. This section is retained for reference only.
-
-- **Docs**: https://docs.gtk.org/gio/type_func.VolumeMonitor.get.html
-- **Purpose**: Get system volume monitor for rich metadata
-- **Returns**: Owned `GVolumeMonitor*` reference
-- **Cleanup**: **Must** call `g_object_unref()` when done
-
-**Why Not Used**: GVolumeMonitor can only be safely used from the main thread.
-Node.js native addons use `Napi::AsyncWorker` which runs on libuv thread pool
-worker threads. Using GVolumeMonitor from these threads causes race conditions:
-
-```
-GLib-GObject-CRITICAL: g_object_ref: assertion '!object_already_finalized' failed
-```
-
-The thread-safe `g_unix_mounts_get()` API provides sufficient metadata (fstype,
-mountFrom). Rich metadata (label, uri) is obtained from blkid instead.
-
-### g_volume_monitor_get_mounts (NOT USED)
-
-> ⚠️ **NOT USED**: See above - GVolumeMonitor is not thread-safe.
-
-- **Docs**: https://docs.gtk.org/gio/method.VolumeMonitor.get_mounts.html
-- **Returns**: `GList*` of `GMount*` (caller owns list and references)
-- **Cleanup**: `g_list_free_full(mounts, g_object_unref)`
-
-### GMount / GVolume / GFile Functions (NOT USED)
-
-> ⚠️ **NOT USED**: These require GVolumeMonitor which is not thread-safe.
-
-| Function                         | Returns    | Ownership           |
-| -------------------------------- | ---------- | ------------------- |
-| `g_mount_get_root()`             | `GFile*`   | Caller owns, unref  |
-| `g_mount_get_volume()`           | `GVolume*` | Caller owns, unref  |
-| `g_mount_get_name()`             | `char*`    | Caller owns, g_free |
-| `g_mount_get_default_location()` | `GFile*`   | Caller owns, unref  |
-| `g_file_get_path()`              | `char*`    | Caller owns, g_free |
-| `g_file_get_uri()`               | `char*`    | Caller owns, g_free |
-| `g_volume_get_name()`            | `char*`    | Caller owns, g_free |
-
-**Memory Management Docs**: https://docs.gtk.org/gobject/concepts.html#reference-counting
-
-### GLib Memory Functions
-
-| Function             | Purpose                               |
-| -------------------- | ------------------------------------- |
-| `g_object_unref()`   | Decrement GObject reference count     |
-| `g_free()`           | Free GLib-allocated memory            |
-| `g_list_free()`      | Free GList container only             |
-| `g_list_free_full()` | Free GList and elements with callback |
-
-**Docs**: https://docs.gtk.org/glib/func.free.html
+1. [libblkid APIs](#libblkid-apis)
+2. [POSIX File System APIs](#posix-file-system-apis)
+3. [RAII Patterns](#raii-patterns)
+4. [References](#references)
 
 ## libblkid APIs
 
@@ -221,32 +116,6 @@ if (fd < 0) {
 
 ## RAII Patterns
 
-### GIO Smart Pointers (gio_utils.h)
-
-```cpp
-// Custom deleters
-template <typename T> struct GObjectDeleter {
-    void operator()(T *ptr) const { if (ptr) g_object_unref(ptr); }
-};
-
-struct GFreeDeleter {
-    void operator()(void *ptr) const { if (ptr) g_free(ptr); }
-};
-
-// Smart pointer aliases
-template <typename T> using GObjectPtr = std::unique_ptr<T, GObjectDeleter<T>>;
-
-using GFilePtr = GObjectPtr<GFile>;
-using GMountPtr = GObjectPtr<GMount>;
-using GVolumePtr = GObjectPtr<GVolume>;
-using GVolumeMonitorPtr = GObjectPtr<GVolumeMonitor>;  // Not currently used
-using GCharPtr = std::unique_ptr<char, GFreeDeleter>;
-```
-
-> **Note**: `GVolumeMonitorPtr`, `GMountPtr`, `GVolumePtr`, and `GFilePtr` are
-> defined but not currently used because GVolumeMonitor is not thread-safe.
-> They are retained for potential future use if a main-thread-only API is added.
-
 ### BlkidCache RAII
 
 ```cpp
@@ -285,18 +154,6 @@ FdGuard guard{fd};
 
 ## References
 
-### GIO/GLib Official Documentation
-
-- [GIO Reference](https://docs.gtk.org/gio/)
-- [GLib Reference](https://docs.gtk.org/glib/)
-- [GObject Memory Management](https://docs.gtk.org/gobject/concepts.html#reference-counting)
-- [GVolumeMonitor](https://docs.gtk.org/gio/class.VolumeMonitor.html)
-- [Unix Mounts](https://docs.gtk.org/gio-unix/struct.MountEntry.html)
-
-### GLib Source Code
-
-- [gunixmounts.c](https://gitlab.gnome.org/GNOME/glib/-/blob/main/gio/gunixmounts.c) - Thread-safe mount enumeration implementation
-
 ### libblkid / util-linux
 
 - [libblkid(3) man page](https://man7.org/linux/man-pages/man3/libblkid.3.html)

package/doc/SECURITY_AUDIT_2026.md

@@ -5,6 +5,10 @@
 **Scope**: Complete codebase review including API verification against official documentation
 **Previous Audit**: October-December 2025 (see `doc/SECURITY_AUDIT_2025.md`)
 
+> **Post-audit note (April 2026):** The Linux GIO/GLib integration discussed in
+> re-verification findings #6 and #7 has since been removed entirely. See the
+> "Removed" section of `CHANGELOG.md` for the rationale.
+
 ## Executive Summary
 
 This audit covers all changes since the December 2025 re-audit, focusing on the new
@@ -190,6 +194,7 @@ A caller could theoretically provide a malicious pattern causing ReDoS.
 **Files**: `src/windows/volume_mount_points.cpp`, `src/windows/volume_metadata.cpp`, `src/windows/system_volume.h`
 
 **Issue**: `GetVolumeInformationW` was called redundantly:
+
 - In `volume_mount_points.cpp`: once for `fstype`/`isReadOnly`, then again inside `IsSystemVolume()`
 - In `volume_metadata.cpp`: `IsSystemVolume()` queried the API, then `VolumeInfo` queried it again 5 lines later
 

package/doc/gotchas.md

@@ -133,6 +133,33 @@ FROM debian:bullseye
 RUN apt-get update && apt-get install -y nodejs npm
 ```
 
+#### Electron Consumers Need libblkid Headers
+
+**Problem**: Electron apps that bundle `@photostructure/fs-metadata` fail to build on Linux with:
+
+```
+fatal error: blkid/blkid.h: No such file or directory
+```
+
+…even though `npm install` reports that prebuilds were found.
+
+**Why it happens**: `@electron/rebuild` (invoked by `electron-forge`, `electron-builder`, and friends) **always recompiles native modules from source** against Electron's bundled Node ABI. The Node-ABI prebuilds shipped in `prebuilds/` are not Electron-compatible and are ignored. The fresh compile then needs the same system headers a from-source build needs.
+
+**Solution**: Install `libblkid-dev` (and friends) on the build machine before running `electron-rebuild` / `electron-forge package`:
+
+```bash
+# Debian/Ubuntu
+sudo apt-get install -y libblkid-dev
+
+# Fedora/RHEL
+sudo dnf install -y libblkid-devel
+
+# Alpine
+apk add blkid-dev
+```
+
+In CI, add this as a step before `npm install` / the Electron package step. The same applies to any consumer that compiles from source for an unsupported architecture or glibc version. See [CONTRIBUTING.md](../CONTRIBUTING.md#on-ubuntudebian) for the full development dependency list.
+
 #### System Volume Filtering
 
 Many mount points on Linux are system-only:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photostructure/fs-metadata",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Cross-platform native filesystem metadata retrieval for Node.js",
   "homepage": "https://photostructure.github.io/fs-metadata/",
   "types": "./dist/index.d.ts",
@@ -31,9 +31,8 @@
     "clean:gyp-cache": "del-cli --force build %USERPROFILE%/.node-gyp ~/.node-gyp",
     "clean:native": "node-gyp clean",
     "node-gyp-rebuild": "node-gyp rebuild",
-    "setup:native": "node scripts/setup-native.mjs",
-    "build": "run-s setup:native build:native build:dist",
-    "build:native": "npm run setup:native && tsx scripts/prebuildify-wrapper.ts",
+    "build": "run-s build:native build:dist",
+    "build:native": "tsx scripts/prebuildify-wrapper.ts",
     "build:linux-glibc": "bash scripts/prebuild-linux-glibc.sh",
     "build:dist": "tsup && node scripts/post-build.mjs",
     "docs": "typedoc",
@@ -96,28 +95,28 @@
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
-    "@types/node": "^25.5.0",
+    "@types/node": "^25.6.0",
     "@types/semver": "^7.7.1",
     "cross-env": "^10.1.0",
     "del-cli": "^7.0.0",
     "eslint": "9.39.1",
     "eslint-plugin-regexp": "^3.1.0",
     "eslint-plugin-security": "^4.0.0",
-    "globals": "^17.4.0",
+    "globals": "^17.5.0",
     "jest": "^30.3.0",
     "jest-environment-node": "^30.3.0",
     "jest-extended": "^7.0.0",
     "node-gyp": "^12.2.0",
-    "npm-check-updates": "^19.6.6",
+    "npm-check-updates": "^21.0.2",
     "npm-run-all2": "8.0.4",
     "prebuildify": "^6.0.1",
-    "prettier": "^3.8.1",
+    "prettier": "^3.8.3",
     "prettier-plugin-organize-imports": "4.3.0",
     "terser": "^5.46.1",
-    "ts-jest": "^29.4.6",
+    "ts-jest": "^29.4.9",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",
-    "typedoc": "^0.28.18",
+    "typedoc": "^0.28.19",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.57.2"
   }

package/scripts/clang-tidy.ts

@@ -140,8 +140,6 @@ async function generateWindowsCompileCommands(): Promise<boolean> {
   console.log("Generating compile_commands.json for Windows...");
 
   try {
-    execSync("npm run setup:native", { stdio: "inherit" });
-
     const nodeVersion = process.version.slice(1);
 
     // Try multiple possible locations for node-gyp headers
@@ -293,7 +291,7 @@ async function generateUnixCompileCommands(): Promise<void> {
     process.exit(1);
   }
 
-  execSync("npm run setup:native && bear -- npm run node-gyp-rebuild", {
+  execSync("bear -- npm run node-gyp-rebuild", {
     stdio: "inherit",
   });
 

package/scripts/prebuild-linux-glibc.sh

@@ -88,7 +88,7 @@ docker cp . "$CONTAINER_NAME:/tmp/project"
 docker exec "$CONTAINER_NAME" sh -c "
   cd /tmp/project && \
   apt-get update -qq && \
-  apt-get install -y -qq build-essential python3 libglib2.0-dev libblkid-dev uuid-dev git && \
+  apt-get install -y -qq build-essential python3 libblkid-dev uuid-dev git && \
   # Verify versions
   echo 'Python version:' && python3 --version && \
   echo 'GCC version:' && gcc --version | head -1 && \
@@ -100,7 +100,6 @@ docker exec "$CONTAINER_NAME" sh -c "
 # Copy artifacts back
 docker cp "$CONTAINER_NAME:/tmp/project/prebuilds" . 2>/dev/null || true
 docker cp "$CONTAINER_NAME:/tmp/project/build" . 2>/dev/null || true
-docker cp "$CONTAINER_NAME:/tmp/project/config.gypi" . 2>/dev/null || true
 
 # Fix ownership (docker cp preserves container's root ownership)
 if [ -d prebuilds ]; then
@@ -109,9 +108,6 @@ fi
 if [ -d build ]; then
   chown -R "$(id -u):$(id -g)" build
 fi
-if [ -f config.gypi ]; then
-  chown "$(id -u):$(id -g)" config.gypi
-fi
 
 # Clean up container
 docker rm -f "$CONTAINER_NAME" >/dev/null

package/scripts/sanitizers-test.sh

@@ -76,7 +76,6 @@ fi
 
 # Build the native module
 echo "Building with AddressSanitizer..."
-npm run setup:native
 npm run clean:native
 npm run node-gyp-rebuild
 

package/src/binding.cpp

@@ -12,10 +12,6 @@
 #include "darwin/hidden.h"
 #elif defined(__linux__)
 #include "common/volume_metadata.h"
-#ifdef ENABLE_GIO
-#include "linux/gio_mount_points.h"
-#include "linux/gio_volume_metadata.h"
-#endif
 #endif
 
 namespace {
@@ -43,13 +39,6 @@ Napi::Value SetDebugPrefix(const Napi::CallbackInfo &info) {
   return env.Undefined();
 }
 
-#ifdef ENABLE_GIO
-Napi::Value GetGioMountPoints(const Napi::CallbackInfo &info) {
-  const Napi::Env env = info.Env();
-  return FSMeta::gio::GetMountPoints(env);
-}
-#endif
-
 #if defined(_WIN32) || defined(__APPLE__)
 // Fix: Remove extra parameter and use correct signature
 Napi::Value GetVolumeMountPoints(const Napi::CallbackInfo &info) {
@@ -92,10 +81,6 @@ Napi::Object Init(Napi::Env env, Napi::Object exports) {
   exports.Set("getMountPoint", Napi::Function::New(env, GetMountPointForPath));
 #endif
 
-#ifdef ENABLE_GIO
-  exports.Set("getGioMountPoints", Napi::Function::New(env, GetGioMountPoints));
-#endif
-
 #if defined(_WIN32) || defined(__APPLE__)
   exports.Set("isHidden", Napi::Function::New(env, GetHiddenAttribute));
   exports.Set("setHidden", Napi::Function::New(env, SetHiddenAttribute));

package/src/index.ts

@@ -122,7 +122,9 @@ export function getVolumeMetadata(
  */
 export function getVolumeMetadataForPath(
   pathname: string,
-  opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>,
+  opts?: Partial<
+    Pick<Options, "timeoutMs" | "linuxMountTablePaths" | "mountPoints">
+  >,
 ): Promise<VolumeMetadata> {
   return getVolumeMetadataForPathImpl(
     pathname,
@@ -148,7 +150,9 @@ export function getVolumeMetadataForPath(
  */
 export function getMountPointForPath(
   pathname: string,
-  opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>,
+  opts?: Partial<
+    Pick<Options, "timeoutMs" | "linuxMountTablePaths" | "mountPoints">
+  >,
 ): Promise<string> {
   return getMountPointForPathImpl(
     pathname,

package/src/linux/mount_points.ts

@@ -2,69 +2,35 @@
 import { readFile } from "node:fs/promises";
 import { debug } from "../debuglog";
 import { toError, WrappedError } from "../error";
-import { isMountPoint } from "../mount_point";
-import { compactValues } from "../object";
 import { optionsWithDefaults } from "../options";
 import { type MountPoint } from "../types/mount_point";
-import type { NativeBindingsFn } from "../types/native_bindings";
 import type { Options } from "../types/options";
 import { MountEntry, mountEntryToMountPoint, parseMtab } from "./mtab";
 
 export async function getLinuxMountPoints(
-  native: NativeBindingsFn,
   opts?: Pick<Options, "linuxMountTablePaths">,
 ): Promise<MountPoint[]> {
   const o = optionsWithDefaults(opts);
-  const raw: MountPoint[] = [];
-  try {
-    // Get GIO mounts if available from native module
-    const arr = await (await native()).getGioMountPoints?.();
-    debug("[getLinuxMountPoints] GIO mount points: %o", arr);
-    if (arr != null) raw.push(...arr);
-  } catch (error) {
-    debug("Failed to get GIO mount points: %s", error);
-    // GIO support not compiled in or failed, continue with just mtab mounts
-  }
-
   let cause: Error | undefined;
   for (const input of o.linuxMountTablePaths) {
     try {
       const mtabContent = await readFile(input, "utf8");
-      const arr = parseMtab(mtabContent)
+      const results = parseMtab(mtabContent)
         .map((ea) => mountEntryToMountPoint(ea))
         .filter((ea) => ea != null);
-      debug("[getLinuxMountPoints] %s mount points: %o", input, arr);
-      if (arr.length > 0) {
-        raw.push(...arr);
-        break;
+      debug("[getLinuxMountPoints] %s mount points: %o", input, results);
+      if (results.length > 0) {
+        return results;
       }
     } catch (error) {
       cause ??= toError(error);
     }
   }
 
-  const byMountPoint = new Map<string, MountPoint>();
-  for (const ea of raw) {
-    const prior = byMountPoint.get(ea.mountPoint);
-    const merged = { ...compactValues(prior), ...compactValues(ea) };
-    if (isMountPoint(merged)) {
-      byMountPoint.set(merged.mountPoint, merged);
-    }
-  }
-
-  if (byMountPoint.size === 0) {
-    throw new WrappedError(
-      `Failed to find any mount points (tried: ${JSON.stringify(o.linuxMountTablePaths)})`,
-      { cause },
-    );
-  }
-
-  const results = [...byMountPoint.values()];
-  debug("[getLinuxMountPoints] %o", {
-    results: results.map((ea) => ea.mountPoint),
-  });
-
-  return results;
+  throw new WrappedError(
+    `Failed to find any mount points (tried: ${JSON.stringify(o.linuxMountTablePaths)})`,
+    { cause },
+  );
 }
 
 export async function getLinuxMtabMetadata(

package/src/linux/volume_metadata.cpp

@@ -12,10 +12,6 @@
 #include <sys/statvfs.h>
 #include <unistd.h>
 
-#ifdef ENABLE_GIO
-#include "gio_volume_metadata.h"
-#endif
-
 namespace FSMeta {
 
 class LinuxMetadataWorker : public MetadataWorkerBase {
@@ -113,18 +109,6 @@ public:
                 mountPoint.c_str(), metadata.size / 1e9,
                 metadata.available / 1e9);
 
-#ifdef ENABLE_GIO
-      try {
-        DEBUG_LOG("[LinuxMetadataWorker] collecting GIO metadata for %s",
-                  validated_mount_point.c_str());
-        gio::addMountMetadata(validated_mount_point, metadata);
-      } catch (const std::exception &e) {
-        DEBUG_LOG("[LinuxMetadataWorker] GIO error for %s: %s",
-                  validated_mount_point.c_str(), e.what());
-        metadata.status = std::string("GIO warning: ") + e.what();
-      }
-#endif
-
       if (!options_.device.empty()) {
         DEBUG_LOG("[LinuxMetadataWorker] getting blkid info for device %s",
                   options_.device.c_str());

package/src/mount_point_for_path.ts

@@ -48,7 +48,7 @@ export async function getMountPointForPathImpl(
     throw new Error("getMountPoint native function unavailable");
   }
 
-  // Linux/Windows: device ID matching + path prefix tiebreaker
+  // Linux/Windows: device ID filtering + longest ancestor path matching
   debug("[getMountPointForPath] using device matching for %s", resolved);
   return findMountPointByDeviceId(resolved, resolvedStat, opts, nativeFn);
 }

package/src/types/mount_point.ts

@@ -29,7 +29,7 @@ export interface MountPoint {
    * verifyVolume`.
    *
    * If there are non-critical errors while extracting metadata, those error
-   * messages may be added to this field (say, from blkid or gio).
+   * messages may be added to this field (say, from blkid).
    *
    * @see {@link VolumeHealthStatuses} for values returned by Windows.
    */

package/src/types/native_bindings.ts

@@ -43,11 +43,6 @@ export interface NativeBindings {
     options?: Pick<Options, "timeoutMs">,
   ): Promise<MountPoint[]>;
 
-  /**
-   * This is only available on Linux, and only if libglib-2.0 is installed.
-   */
-  getGioMountPoints?(): Promise<MountPoint[]>;
-
   /**
    * This is only a partial implementation for most platforms, to minimize
    * native code when possible. The javascript side handles a bunch of

package/src/types/options.ts

@@ -1,5 +1,7 @@
 // src/types/options.ts
 
+import type { MountPoint } from "./mount_point";
+
 /**
  * Configuration options for filesystem operations.
  *
@@ -7,6 +9,18 @@
  * @see {@link OptionsDefault} for the default values
  */
 export interface Options {
+  /**
+   * Pre-fetched mount points to use instead of querying the system.
+   *
+   * When provided, functions like {@link getMountPointForPath} and
+   * {@link getVolumeMetadataForPath} will use these mount points for device ID
+   * matching instead of calling {@link getVolumeMountPoints} internally. This
+   * avoids redundant system queries when resolving multiple paths.
+   *
+   * Obtain via `getVolumeMountPoints({ includeSystemVolumes: true })` — system
+   * volumes must be included for device ID matching to work correctly.
+   */
+  mountPoints?: MountPoint[];
   /**
    * Timeout in milliseconds for filesystem operations.
    *