@photostructure/fs-metadata 1.0.1 → 1.1.0

package/dist/index.d.cts

@@ -88,11 +88,36 @@ interface MountPoint {
      * Indicates if this volume is primarily for system use (e.g., swap, snap
      * loopbacks, EFI boot, or only system directories).
      *
-     * Note: This is a best-effort classification and is not 100% accurate.
+     * On macOS, the sealed APFS system snapshot at `/` is detected natively via
+     * `MNT_SNAPSHOT`; other infrastructure volumes under `/System/Volumes/*` are
+     * detected via APFS volume roles (IOKit). Note that `/System/Volumes/Data`
+     * is **not** a system volume — it holds all user data, accessed via firmlinks.
      *
      * @see {@link Options.systemPathPatterns} and {@link Options.systemFsTypes}
      */
     isSystemVolume?: boolean;
+    /**
+     * The APFS volume role, if available. Only present on macOS for APFS volumes.
+     *
+     * Common roles: `"System"`, `"Data"`, `"VM"`, `"Preboot"`, `"Recovery"`,
+     * `"Update"`, `"Hardware"`, `"xART"`, `"Prelogin"`, `"Backup"`.
+     *
+     * Used for system volume detection: volumes with a non-`"Data"` role and
+     * `MNT_DONTBROWSE` are classified as system volumes.
+     *
+     * @see https://eclecticlight.co/2024/11/21/how-do-apfs-volume-roles-work/
+     */
+    volumeRole?: string;
+    /**
+     * Whether the volume is mounted read-only.
+     *
+     * Examples of read-only volumes include the macOS APFS system snapshot at
+     * `/`, mounted ISO images, and write-protected media.
+     *
+     * Note that the macOS root volume (`/`) UUID changes on every OS update, so
+     * consumers should avoid using it for persistent identification.
+     */
+    isReadOnly?: boolean;
     /**
      * If there are non-critical errors while extracting metadata, those errors
      * may be added to this field.
@@ -262,7 +287,7 @@ declare function getTimeoutMsDefault(): number;
 /**
  * System paths and globs that indicate system volumes
  */
-declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm", "/System/Volumes/Hardware", "/System/Volumes/iSCPreboot", "/System/Volumes/Preboot", "/System/Volumes/Recovery", "/System/Volumes/Reserved", "/System/Volumes/Update", "/System/Volumes/VM", "/System/Volumes/xarts", "**/.DocumentRevisions-V100", "**/.fseventsd", "**/.Spotlight-V100", "**/.Trashes"];
+declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm"];
 /**
  * Filesystem types that indicate system/virtual volumes.
  *
@@ -332,6 +357,17 @@ declare function getVolumeMountPoints(opts?: Partial<GetVolumeMountPointOptions>
  * @param opts Optional filesystem operation settings
  */
 declare function getVolumeMetadata(mountPoint: string, opts?: Partial<Pick<Options, "timeoutMs">>): Promise<VolumeMetadata>;
+/**
+ * Get metadata for the volume that contains the given file or directory path.
+ *
+ * Unlike {@link getVolumeMetadata}, this accepts any path — not just mount
+ * points. Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly, mirroring what `df` does.
+ *
+ * @param pathname Path to any file or directory
+ * @param opts Optional filesystem operation settings
+ */
+declare function getVolumeMetadataForPath(pathname: string, opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>): Promise<VolumeMetadata>;
 /**
  * Retrieves metadata for all mounted volumes with optional filtering and
  * concurrency control.
@@ -393,4 +429,4 @@ declare function getHiddenMetadata(pathname: string): Promise<HiddenMetadata>;
  */
 declare function setHidden(pathname: string, hidden: boolean, method?: HideMethod): Promise<SetHiddenResult>;
 
-export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getTimeoutMsDefault, getVolumeMetadata, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };
+export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getTimeoutMsDefault, getVolumeMetadata, getVolumeMetadataForPath, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };

package/dist/index.d.mts

@@ -88,11 +88,36 @@ interface MountPoint {
      * Indicates if this volume is primarily for system use (e.g., swap, snap
      * loopbacks, EFI boot, or only system directories).
      *
-     * Note: This is a best-effort classification and is not 100% accurate.
+     * On macOS, the sealed APFS system snapshot at `/` is detected natively via
+     * `MNT_SNAPSHOT`; other infrastructure volumes under `/System/Volumes/*` are
+     * detected via APFS volume roles (IOKit). Note that `/System/Volumes/Data`
+     * is **not** a system volume — it holds all user data, accessed via firmlinks.
      *
      * @see {@link Options.systemPathPatterns} and {@link Options.systemFsTypes}
      */
     isSystemVolume?: boolean;
+    /**
+     * The APFS volume role, if available. Only present on macOS for APFS volumes.
+     *
+     * Common roles: `"System"`, `"Data"`, `"VM"`, `"Preboot"`, `"Recovery"`,
+     * `"Update"`, `"Hardware"`, `"xART"`, `"Prelogin"`, `"Backup"`.
+     *
+     * Used for system volume detection: volumes with a non-`"Data"` role and
+     * `MNT_DONTBROWSE` are classified as system volumes.
+     *
+     * @see https://eclecticlight.co/2024/11/21/how-do-apfs-volume-roles-work/
+     */
+    volumeRole?: string;
+    /**
+     * Whether the volume is mounted read-only.
+     *
+     * Examples of read-only volumes include the macOS APFS system snapshot at
+     * `/`, mounted ISO images, and write-protected media.
+     *
+     * Note that the macOS root volume (`/`) UUID changes on every OS update, so
+     * consumers should avoid using it for persistent identification.
+     */
+    isReadOnly?: boolean;
     /**
      * If there are non-critical errors while extracting metadata, those errors
      * may be added to this field.
@@ -262,7 +287,7 @@ declare function getTimeoutMsDefault(): number;
 /**
  * System paths and globs that indicate system volumes
  */
-declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm", "/System/Volumes/Hardware", "/System/Volumes/iSCPreboot", "/System/Volumes/Preboot", "/System/Volumes/Recovery", "/System/Volumes/Reserved", "/System/Volumes/Update", "/System/Volumes/VM", "/System/Volumes/xarts", "**/.DocumentRevisions-V100", "**/.fseventsd", "**/.Spotlight-V100", "**/.Trashes"];
+declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm"];
 /**
  * Filesystem types that indicate system/virtual volumes.
  *
@@ -332,6 +357,17 @@ declare function getVolumeMountPoints(opts?: Partial<GetVolumeMountPointOptions>
  * @param opts Optional filesystem operation settings
  */
 declare function getVolumeMetadata(mountPoint: string, opts?: Partial<Pick<Options, "timeoutMs">>): Promise<VolumeMetadata>;
+/**
+ * Get metadata for the volume that contains the given file or directory path.
+ *
+ * Unlike {@link getVolumeMetadata}, this accepts any path — not just mount
+ * points. Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly, mirroring what `df` does.
+ *
+ * @param pathname Path to any file or directory
+ * @param opts Optional filesystem operation settings
+ */
+declare function getVolumeMetadataForPath(pathname: string, opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>): Promise<VolumeMetadata>;
 /**
  * Retrieves metadata for all mounted volumes with optional filtering and
  * concurrency control.
@@ -393,4 +429,4 @@ declare function getHiddenMetadata(pathname: string): Promise<HiddenMetadata>;
  */
 declare function setHidden(pathname: string, hidden: boolean, method?: HideMethod): Promise<SetHiddenResult>;
 
-export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getTimeoutMsDefault, getVolumeMetadata, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };
+export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getTimeoutMsDefault, getVolumeMetadata, getVolumeMetadataForPath, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };

package/dist/index.d.ts

@@ -88,11 +88,36 @@ interface MountPoint {
      * Indicates if this volume is primarily for system use (e.g., swap, snap
      * loopbacks, EFI boot, or only system directories).
      *
-     * Note: This is a best-effort classification and is not 100% accurate.
+     * On macOS, the sealed APFS system snapshot at `/` is detected natively via
+     * `MNT_SNAPSHOT`; other infrastructure volumes under `/System/Volumes/*` are
+     * detected via APFS volume roles (IOKit). Note that `/System/Volumes/Data`
+     * is **not** a system volume — it holds all user data, accessed via firmlinks.
      *
      * @see {@link Options.systemPathPatterns} and {@link Options.systemFsTypes}
      */
     isSystemVolume?: boolean;
+    /**
+     * The APFS volume role, if available. Only present on macOS for APFS volumes.
+     *
+     * Common roles: `"System"`, `"Data"`, `"VM"`, `"Preboot"`, `"Recovery"`,
+     * `"Update"`, `"Hardware"`, `"xART"`, `"Prelogin"`, `"Backup"`.
+     *
+     * Used for system volume detection: volumes with a non-`"Data"` role and
+     * `MNT_DONTBROWSE` are classified as system volumes.
+     *
+     * @see https://eclecticlight.co/2024/11/21/how-do-apfs-volume-roles-work/
+     */
+    volumeRole?: string;
+    /**
+     * Whether the volume is mounted read-only.
+     *
+     * Examples of read-only volumes include the macOS APFS system snapshot at
+     * `/`, mounted ISO images, and write-protected media.
+     *
+     * Note that the macOS root volume (`/`) UUID changes on every OS update, so
+     * consumers should avoid using it for persistent identification.
+     */
+    isReadOnly?: boolean;
     /**
      * If there are non-critical errors while extracting metadata, those errors
      * may be added to this field.
@@ -262,7 +287,7 @@ declare function getTimeoutMsDefault(): number;
 /**
  * System paths and globs that indicate system volumes
  */
-declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm", "/System/Volumes/Hardware", "/System/Volumes/iSCPreboot", "/System/Volumes/Preboot", "/System/Volumes/Recovery", "/System/Volumes/Reserved", "/System/Volumes/Update", "/System/Volumes/VM", "/System/Volumes/xarts", "**/.DocumentRevisions-V100", "**/.fseventsd", "**/.Spotlight-V100", "**/.Trashes"];
+declare const SystemPathPatternsDefault: readonly ["/boot", "/boot/efi", "/dev", "/dev/**", "/proc/**", "/run", "/run/credentials/**", "/run/flatpak/**", "/run/lock", "/run/snapd/**", "/run/user/*/doc", "/run/user/*/gvfs", "/snap/**", "/sys/**", "/tmp", "/var/tmp", "**/#snapshot", "/run/docker/**", "/var/lib/docker/**", "/run/containerd/**", "/var/lib/containerd/**", "/run/containers/**", "/var/lib/containers/**", "/var/lib/kubelet/**", "/var/lib/lxc/**", "/var/lib/lxd/**", "/mnt/wslg/distro", "/mnt/wslg/doc", "/mnt/wslg/versions.txt", "/usr/lib/wsl/drivers", "/private/var/vm"];
 /**
  * Filesystem types that indicate system/virtual volumes.
  *
@@ -332,6 +357,17 @@ declare function getVolumeMountPoints(opts?: Partial<GetVolumeMountPointOptions>
  * @param opts Optional filesystem operation settings
  */
 declare function getVolumeMetadata(mountPoint: string, opts?: Partial<Pick<Options, "timeoutMs">>): Promise<VolumeMetadata>;
+/**
+ * Get metadata for the volume that contains the given file or directory path.
+ *
+ * Unlike {@link getVolumeMetadata}, this accepts any path — not just mount
+ * points. Symlinks are resolved, and macOS APFS firmlinks (e.g. `/Users` →
+ * `/System/Volumes/Data`) are handled correctly, mirroring what `df` does.
+ *
+ * @param pathname Path to any file or directory
+ * @param opts Optional filesystem operation settings
+ */
+declare function getVolumeMetadataForPath(pathname: string, opts?: Partial<Pick<Options, "timeoutMs" | "linuxMountTablePaths">>): Promise<VolumeMetadata>;
 /**
  * Retrieves metadata for all mounted volumes with optional filtering and
  * concurrency control.
@@ -393,4 +429,4 @@ declare function getHiddenMetadata(pathname: string): Promise<HiddenMetadata>;
  */
 declare function setHidden(pathname: string, hidden: boolean, method?: HideMethod): Promise<SetHiddenResult>;
 
-export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getTimeoutMsDefault, getVolumeMetadata, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };
+export { type GetVolumeMountPointOptions, type HiddenMetadata, type HideMethod, IncludeSystemVolumesDefault, LinuxMountTablePathsDefault, type MountPoint, NetworkFsTypesDefault, type Options, OptionsDefault, type SetHiddenResult, SkipNetworkVolumesDefault, type StringEnum, type StringEnumKeys, type StringEnumType, SystemFsTypesDefault, SystemPathPatternsDefault, type SystemVolumeConfig, type VolumeHealthStatus, VolumeHealthStatuses, type VolumeMetadata, getAllVolumeMetadata, getHiddenMetadata, getTimeoutMsDefault, getVolumeMetadata, getVolumeMetadataForPath, getVolumeMountPoints, isHidden, isHiddenRecursive, optionsWithDefaults, setHidden };

package/dist/index.mjs

@@ -388,7 +388,7 @@ function toError(cause) {
 }
 
 // src/path.ts
-import { dirname as dirname2, resolve as resolve2 } from "path";
+import { dirname as dirname2, resolve as resolve2, sep } from "path";
 function normalizePath(mountPoint) {
   if (isBlank(mountPoint)) return void 0;
   if (mountPoint.includes("..")) {
@@ -417,6 +417,11 @@ function isRootDirectory(path2) {
   const n = normalizePath(path2);
   return n == null ? false : isWindows ? dirname2(n) === n : n === "/";
 }
+function isAncestorOrSelf(ancestor, descendant) {
+  if (ancestor === descendant) return true;
+  const prefix = isRootDirectory(ancestor) ? ancestor : ancestor + sep;
+  return descendant.startsWith(prefix);
+}
 
 // src/hidden.ts
 var HiddenSupportByPlatform = {
@@ -643,23 +648,13 @@ var SystemPathPatternsDefault = [
   "/mnt/wslg/doc",
   "/mnt/wslg/versions.txt",
   "/usr/lib/wsl/drivers",
-  // macOS system paths:
-  "/private/var/vm",
-  // macOS swap
-  "/System/Volumes/Hardware",
-  "/System/Volumes/iSCPreboot",
-  "/System/Volumes/Preboot",
-  "/System/Volumes/Recovery",
-  "/System/Volumes/Reserved",
-  "/System/Volumes/Update",
-  "/System/Volumes/VM",
-  "/System/Volumes/xarts",
-  // macOS per-volume metadata (Spotlight, FSEvents, versioning, Trash):
-  // https://eclecticlight.co/2021/01/28/spotlight-on-search-how-spotlight-works/
-  "**/.DocumentRevisions-V100",
-  "**/.fseventsd",
-  "**/.Spotlight-V100",
-  "**/.Trashes"
+  // macOS system volumes are detected natively via APFS volume roles
+  // (IOKit IOMedia "Role" property) with MNT_SNAPSHOT as a fallback.
+  // No path patterns needed. See src/darwin/system_volume.h.
+  //
+  // /private/var/vm is the macOS swap directory (not a mount point on most
+  // systems, but included for completeness if it appears as one).
+  "/private/var/vm"
 ];
 var SystemFsTypesDefault = [
   "autofs",
@@ -834,6 +829,10 @@ async function directoryStatus(dir, timeoutMs, canReaddirImpl = canReaddir) {
   return { status: VolumeHealthStatuses.unknown };
 }
 
+// src/volume_metadata.ts
+import { realpath } from "fs/promises";
+import { dirname as dirname4 } from "path";
+
 // src/linux/dev_disk.ts
 import { readdir, readlink } from "fs/promises";
 import { join as join3, resolve as resolve3 } from "path";
@@ -1118,20 +1117,20 @@ function isSystemVolume(mountPoint, fstype, config = {}) {
 }
 function assignSystemVolume(mp, config) {
   const result = isSystemVolume(mp.mountPoint, mp.fstype, config);
-  if (isWindows) {
-    mp.isSystemVolume ??= result;
-  } else {
-    mp.isSystemVolume = result;
-  }
+  mp.isSystemVolume = mp.isSystemVolume || result;
 }
 
 // src/linux/mtab.ts
+function isReadOnlyMount(fs_mntops) {
+  return fs_mntops?.split(",").includes("ro") ?? false;
+}
 function mountEntryToMountPoint(entry) {
   const mountPoint = normalizePosixPath(entry.fs_file);
   const fstype = toNotBlank(entry.fs_vfstype) ?? toNotBlank(entry.fs_spec);
   return mountPoint == null || fstype == null ? void 0 : {
     mountPoint,
-    fstype
+    fstype,
+    isReadOnly: isReadOnlyMount(entry.fs_mntops)
   };
 }
 function mountEntryToPartialVolumeMetadata(entry, options = {}) {
@@ -1141,6 +1140,7 @@ function mountEntryToPartialVolumeMetadata(entry, options = {}) {
     fstype: entry.fs_vfstype,
     mountFrom: entry.fs_spec,
     isSystemVolume: isSystemVolume(entry.fs_file, entry.fs_vfstype, options),
+    isReadOnly: isReadOnlyMount(entry.fs_mntops),
     remote: false,
     // < default to false, but it may be overridden by extractRemoteInfo
     ...extractRemoteInfo(entry.fs_spec, networkFsTypes)
@@ -1424,6 +1424,57 @@ async function _getVolumeMetadata(o, nativeFn2) {
   debug("[getVolumeMetadata] final result for %s: %o", o.mountPoint, result);
   return compactValues(result);
 }
+async function getVolumeMetadataForPathImpl(pathname, opts, nativeFn2) {
+  if (isBlank(pathname)) {
+    throw new TypeError("Invalid pathname: got " + JSON.stringify(pathname));
+  }
+  const resolved = await realpath(pathname);
+  const resolvedStat = await statAsync(resolved);
+  const dir = resolvedStat.isDirectory() ? resolved : dirname4(resolved);
+  if (isMacOS) {
+    const probe = await getVolumeMetadataImpl(
+      { ...opts, mountPoint: dir },
+      nativeFn2
+    );
+    const canonicalMountPoint = isNotBlank(probe.mountName) ? probe.mountName : dir;
+    if (canonicalMountPoint === dir) return probe;
+    return getVolumeMetadataImpl(
+      { ...opts, mountPoint: canonicalMountPoint },
+      nativeFn2
+    );
+  }
+  const targetDev = resolvedStat.dev;
+  const mountPoints = await getVolumeMountPointsImpl(
+    { ...opts, includeSystemVolumes: true },
+    nativeFn2
+  );
+  const prefixMatches = [];
+  const deviceMatches = [];
+  await Promise.all(
+    mountPoints.map(async ({ mountPoint: mountPoint2 }) => {
+      try {
+        const mpDev = (await statAsync(mountPoint2)).dev;
+        if (mpDev !== targetDev) return;
+        if (isAncestorOrSelf(mountPoint2, resolved)) {
+          prefixMatches.push(mountPoint2);
+        } else {
+          deviceMatches.push(mountPoint2);
+        }
+      } catch {
+      }
+    })
+  );
+  const candidates = prefixMatches.length > 0 ? prefixMatches : deviceMatches;
+  if (candidates.length === 0) {
+    throw new Error(
+      "No mount point found for path: " + JSON.stringify(pathname)
+    );
+  }
+  const mountPoint = candidates.reduce(
+    (a, b) => a.length >= b.length ? a : b
+  );
+  return getVolumeMetadataImpl({ ...opts, mountPoint }, nativeFn2);
+}
 async function getAllVolumeMetadataImpl(opts, nativeFn2) {
   const o = optionsWithDefaults(opts);
   debug("[getAllVolumeMetadata] starting with options: %o", o);
@@ -1479,11 +1530,11 @@ async function getAllVolumeMetadataImpl(opts, nativeFn2) {
 var nativeFn = defer2(async () => {
   const start = Date.now();
   try {
-    const dirname4 = _dirname();
-    const dir = await findAncestorDir(dirname4, "binding.gyp");
+    const dirname5 = _dirname();
+    const dir = await findAncestorDir(dirname5, "binding.gyp");
     if (dir == null) {
       throw new Error(
-        "Could not find bindings.gyp in any ancestor directory of " + dirname4
+        "Could not find bindings.gyp in any ancestor directory of " + dirname5
       );
     }
     const bindings = NodeGypBuild(dir);
@@ -1506,6 +1557,13 @@ function getVolumeMetadata(mountPoint, opts) {
     nativeFn
   );
 }
+function getVolumeMetadataForPath(pathname, opts) {
+  return getVolumeMetadataForPathImpl(
+    pathname,
+    optionsWithDefaults(opts),
+    nativeFn
+  );
+}
 function getAllVolumeMetadata(opts) {
   return getAllVolumeMetadataImpl(optionsWithDefaults(opts), nativeFn);
 }
@@ -1534,6 +1592,7 @@ export {
   getHiddenMetadata,
   getTimeoutMsDefault,
   getVolumeMetadata,
+  getVolumeMetadataForPath,
   getVolumeMountPoints,
   isHidden,
   isHiddenRecursive,