@photostructure/fs-metadata 0.3.2 → 0.4.0

package/src/remote_info.ts

@@ -3,41 +3,8 @@
 import { debug } from "./debuglog.js";
 import { compactValues, isObject } from "./object.js";
 import { isWindows } from "./platform.js";
-import { isBlank, isNotBlank } from "./string.js";
-
-/**
- * Represents remote filesystem information.
- */
-export interface RemoteInfo {
-  /**
-   * We can sometimes fetch a URI of the resource (like "smb://server/share" or
-   * "file:///media/user/usb")
-   */
-  uri?: string;
-  /**
-   * Protocol used to access the share.
-   */
-  protocol?: string;
-  /**
-   * Does the protocol seem to be a remote filesystem?
-   */
-  remote: boolean;
-  /**
-   * If remote, may include the username used to access the share.
-   *
-   * This will be undefined on NFS and other remote filesystem types that do
-   * authentication out of band.
-   */
-  remoteUser?: string;
-  /**
-   * If remote, the ip or hostname hosting the share (like "rusty" or "10.1.1.3")
-   */
-  remoteHost?: string;
-  /**
-   * If remote, the name of the share (like "homes")
-   */
-  remoteShare?: string;
-}
+import { isBlank, isNotBlank, toS } from "./string.js";
+import { RemoteInfo } from "./types/remote_info.js";
 
 export function isRemoteInfo(obj: unknown): obj is RemoteInfo {
   if (!isObject(obj)) return false;
@@ -45,7 +12,7 @@ export function isRemoteInfo(obj: unknown): obj is RemoteInfo {
   return isNotBlank(remoteHost) && isNotBlank(remoteShare);
 }
 
-const NETWORK_FS_TYPES = new Set([
+const NETWORK_FS_TYPE_ARRAY = [
   "9p",
   "afp",
   "afs",
@@ -53,9 +20,6 @@ const NETWORK_FS_TYPES = new Set([
   "ceph",
   "cifs",
   "ftp",
-  "fuse.cephfs",
-  "fuse.glusterfs",
-  "fuse.sshfs",
   "fuse",
   "gfs2",
   "glusterfs",
@@ -67,14 +31,40 @@ const NETWORK_FS_TYPES = new Set([
   "smbfs",
   "sshfs",
   "webdav",
-]);
+] as const;
+
+type NetworkFsType = (typeof NETWORK_FS_TYPE_ARRAY)[number];
+
+const NETWORK_FS_TYPES = new Set<NetworkFsType>(NETWORK_FS_TYPE_ARRAY);
+
+const FS_TYPE_ALIASES = new Map<string, NetworkFsType>([
+  ["nfs1", "nfs"],
+  ["nfs2", "nfs"],
+  ["nfs3", "nfs"],
+  ["nfs4", "nfs4"],
+  ["fuse.sshfs", "sshfs"],
+  ["sshfs.fuse", "sshfs"],
+  ["davfs2", "webdav"],
+  ["davfs", "webdav"],
+  ["cifs.smb", "cifs"],
+  ["smbfs", "cifs"],
+  ["cephfs", "ceph"],
+  ["fuse.ceph", "ceph"],
+  ["fuse.cephfs", "ceph"],
+  ["rbd", "ceph"],
+  ["fuse.glusterfs", "glusterfs"],
+] as const);
 
-export function normalizeProtocol(protocol: string): string {
-  return (protocol ?? "").toLowerCase().replace(/:$/, "");
+export function normalizeFsType(fstype: string): string {
+  const norm = toS(fstype).toLowerCase().replace(/:$/, "");
+  return FS_TYPE_ALIASES.get(norm) ?? norm;
 }
 
 export function isRemoteFsType(fstype: string | undefined): boolean {
-  return isNotBlank(fstype) && NETWORK_FS_TYPES.has(normalizeProtocol(fstype));
+  return (
+    isNotBlank(fstype) &&
+    NETWORK_FS_TYPES.has(normalizeFsType(fstype) as NetworkFsType)
+  );
 }
 
 export function parseURL(s: string): URL | undefined {
@@ -104,13 +94,18 @@ export function extractRemoteInfo(
   }
 
   const patterns = [
-    // CIFS/SMB pattern: //hostname/share or //user@host/share
     {
+      // CIFS/SMB pattern: //hostname/share or //user@host/share
       regex:
         /^\/\/(?:(?<remoteUser>[^/@]+)@)?(?<remoteHost>[^/@]+)\/(?<remoteShare>.+)$/,
     },
-    // NFS pattern: hostname:/share
     {
+      // sshfs pattern: sshfs#USER@HOST:REMOTE_PATH
+      regex:
+        /^(?:(?<protocol>\w+)#)?(?<remoteUser>[^@]+)@(?<remoteHost>[^:]+):(?<remoteShare>.+)$/,
+    },
+    {
+      // NFS pattern: hostname:/share
       protocol: "nfs",
       regex: /^(?<remoteHost>[^:]+):\/(?!\/)(?<remoteShare>.+)$/,
     },
@@ -128,14 +123,14 @@ export function extractRemoteInfo(
     }
   }
 
-  // Let's try URL last, as nfs mounts are URI-ish
+  // Let's try URL last, as nfs and webdav mounts are URI-ish
   try {
     // try to parse fsSpec as a uri:
     const parsed = new URL(fsSpec);
     if (parsed != null) {
       debug("[extractRemoteInfo] parsed URL: %o", parsed);
-      const protocol = normalizeProtocol(parsed.protocol);
-      if (!isRemoteFsType(protocol)) {
+      const fstype = normalizeFsType(parsed.protocol);
+      if (!isRemoteFsType(fstype)) {
         // don't set remoteUser, remoteHost, or remoteShare, it's not remote!
         return {
           uri: fsSpec,
@@ -144,7 +139,7 @@ export function extractRemoteInfo(
       } else {
         return compactValues({
           uri: fsSpec,
-          protocol,
+          protocol: fstype,
           remote: true,
           remoteUser: parsed.username,
           remoteHost: parsed.hostname,

package/src/stack_path.ts

@@ -0,0 +1,71 @@
+import { dirname } from "node:path";
+import { isWindows } from "./platform";
+import { isNotBlank, toS } from "./string";
+
+export function getCallerDirname(): string {
+  const e = new Error();
+  if (e.stack == null) {
+    Error.captureStackTrace(e);
+  }
+  return dirname(extractCallerPath(e.stack as string));
+}
+
+// CURSE THE ESM MODULE SYSTEM 💩 THIS IS ALL HORRIBLE
+
+// THANK GOODNESS for tsup shims: this should only be used when running tests.
+
+// Comprehensive regex patterns for different stack frame formats. Note that we
+// only expect tests to have the first standard form, but if something's worth
+// doing, **it's worth overdoing**.
+const patterns = isWindows
+  ? [
+      // Standard: "at functionName (C:\path\file.js:1:1)"
+      /\bat\s.+?\((?<path>[A-Z]:\\.+):\d+:\d+\)$/,
+      // direct: "at C:\path\file.js:1:1"
+      /\bat\s(?<path>[A-Z]:\\.+):\d+:\d+$/,
+      // UNC: "at functionName (\\server\share\path\file.js:1:1)"
+      /\bat\s.+?\((?<path>\\\\.+):\d+:\d+\)$/,
+      // direct: "at \\server\share\path\file.js:1:1"
+      /\bat\s(?<path>\\\\.+):\d+:\d+$/,
+    ]
+  : [
+      // Standard: "at functionName (/path/file.js:1:1)"
+      /\bat\s.+?\((?<path>\/.+?):\d+:\d+\)$/,
+      // Anonymous or direct: "at /path/file.js:1:1"
+      /\bat\s(.+[^/]\s)?(?<path>\/.+?):\d+:\d+$/,
+    ];
+
+const MaybeUrlRE = /^[a-z]{2,5}:\/\//i;
+
+// only exposed for tests:
+export function extractCallerPath(stack: string): string {
+  const frames = stack.split("\n").filter(Boolean);
+
+  // First find getCallerDirname() in the stack:
+  const callerFrame = frames.findIndex((frame) =>
+    frame.includes("getCallerDirname"),
+  );
+  if (callerFrame === -1) {
+    throw new Error("Invalid stack trace format: missing caller frame");
+  }
+  for (let i = callerFrame + 1; i < frames.length; i++) {
+    const frame = frames[i];
+    for (const pattern of patterns) {
+      const g = toS(frame).trim().match(pattern)?.groups;
+      if (g != null && isNotBlank(g["path"])) {
+        const path = g["path"];
+        // Windows requires us to check if it's a reasonable URL, as URL accepts
+        // "C:\\path\\file.txt" as valid (!!)
+        if (MaybeUrlRE.test(path)) {
+          try {
+            return new URL(path).pathname;
+          } catch {
+            // ignore
+          }
+        }
+        return path;
+      }
+    }
+  }
+  throw new Error("Invalid stack trace format: no parsable frames");
+}

package/src/system_volume.ts

@@ -2,15 +2,12 @@
 
 import { debug } from "./debuglog.js";
 import { compileGlob } from "./glob.js";
-import { MountPoint } from "./mount_point.js";
-import {
-  Options,
-  SystemFsTypesDefault,
-  SystemPathPatternsDefault,
-} from "./options.js";
+import { SystemFsTypesDefault, SystemPathPatternsDefault } from "./options.js";
 import { normalizePath } from "./path.js";
 import { isWindows } from "./platform.js";
 import { isNotBlank } from "./string.js";
+import type { MountPoint } from "./types/mount_point.js";
+import type { Options } from "./types/options.js";
 
 /**
  * Configuration for system volume detection

package/src/test-utils/assert.ts

@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/no-non-null-assertion */
 // src/test-utils/assert.ts
 import { isMacOS } from "../platform.js";
-import type { VolumeMetadata } from "../volume_metadata.js";
+import type { VolumeMetadata } from "../types/volume_metadata.js";
 
 /**
  * Asserts that the given metadata object has valid filesystem metadata

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

@@ -0,0 +1,15 @@
+#!/usr/bin/env -S npx tsx
+
+import { debugLogContext, isDebugEnabled } from "../debuglog.js";
+
+try {
+  const result = {
+    isDebugEnabled: isDebugEnabled(),
+    debugLogContext: debugLogContext(),
+  };
+  console.log(JSON.stringify(result));
+  process.exit(0);
+} catch (err) {
+  console.error(err);
+  process.exit(1);
+}

package/src/types/hidden_metadata.ts

@@ -0,0 +1,38 @@
+// src/types/hidden_metadata.ts
+
+/**
+ * Represents the detailed state of a file or directory's hidden attribute
+ */
+export interface HiddenMetadata {
+  /**
+   * Whether the item is considered hidden by any method
+   */
+  hidden: boolean;
+
+  /**
+   * Whether the item has a dot prefix (POSIX-style hidden). Windows doesn't
+   * care about dot prefixes.
+   */
+  dotPrefix: boolean;
+
+  /**
+   * Whether the item has system hidden flags set, like via `chflags` on macOS
+   * or on Windows via `GetFileAttributesW`
+   */
+  systemFlag: boolean;
+
+  /**
+   * Indicates which hiding methods are supported on the current platform
+   */
+  supported: {
+    /**
+     * Whether dot prefix hiding is supported on the current operating system
+     */
+    dotPrefix: boolean;
+
+    /**
+     * Whether system flag hiding is supported
+     */
+    systemFlag: boolean;
+  };
+}

package/src/types/mount_point.ts

@@ -0,0 +1,53 @@
+// src/types/mount_point.ts
+
+import type { VolumeHealthStatus } from "../volume_health_status";
+
+/**
+ * A mount point is a location in the file system where a volume is mounted.
+ *
+ * @see https://en.wikipedia.org/wiki/Mount_(computing)
+ */
+export interface MountPoint {
+  /**
+   * Mount location (like "/" or "C:\").
+   */
+  mountPoint: string;
+
+  /**
+   * The type of file system on the volume, like `ext4`, `apfs`, or `ntfs`.
+   *
+   * Note: on Windows this may show as "ntfs" for remote filesystems, as that
+   * is how the filesystem is presented to the OS.
+   */
+  fstype?: string;
+
+  /**
+   * On Windows, returns the health status of the volume.
+   *
+   * Note that this is only available on Windows, as both Linux and macOS  are
+   * prohibitively expensive, requiring forking `fsck -N` or `diskutil
+   * verifyVolume`.
+   *
+   * If there are non-critical errors while extracting metadata, those error
+   * messages may be added to this field (say, from blkid or gio).
+   *
+   * @see {@link VolumeHealthStatuses} for values returned by Windows.
+   */
+  status?: VolumeHealthStatus | string;
+
+  /**
+   * 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.
+   *
+   * @see {@link Options.systemPathPatterns} and {@link Options.systemFsTypes}
+   */
+  isSystemVolume?: boolean;
+
+  /**
+   * If there are non-critical errors while extracting metadata, those errors
+   * may be added to this field.
+   */
+  error?: Error | string;
+}

package/src/types/native_bindings.ts

@@ -1,8 +1,8 @@
 // src/types/native_bindings.ts
 
-import { MountPoint } from "../mount_point.js";
-import type { Options } from "../options.js";
-import type { VolumeMetadata } from "../volume_metadata.js";
+import type { MountPoint } from "./mount_point.js";
+import type { Options } from "./options.js";
+import type { VolumeMetadata } from "./volume_metadata.js";
 
 export interface NativeBindings {
   /**

package/src/types/options.ts

@@ -0,0 +1,54 @@
+// src/types/options.ts
+
+/**
+ * Configuration options for filesystem operations.
+ *
+ * @see {@link optionsWithDefaults} for creating an options object with default values
+ * @see {@link OptionsDefault} for the default values
+ */
+export interface Options {
+  /**
+   * Timeout in milliseconds for filesystem operations.
+   *
+   * Disable timeouts by setting this to 0.
+   *
+   * @see {@link TimeoutMsDefault}.
+   */
+  timeoutMs: number;
+
+  /**
+   * Maximum number of concurrent filesystem operations.
+   *
+   * Defaults to {@link https://nodejs.org/api/os.html#osavailableparallelism | availableParallelism}.
+   */
+  maxConcurrency: number;
+
+  /**
+   * On Linux and macOS, mount point pathnames that matches any of these glob
+   * patterns will have {@link MountPoint.isSystemVolume} set to true.
+   *
+   * @see {@link SystemPathPatternsDefault} for the default value
+   */
+  systemPathPatterns: string[];
+
+  /**
+   * On Linux and macOS, volumes whose filesystem matches any of these strings
+   * will have {@link MountPoint.isSystemVolume} set to true.
+   *
+   * @see {@link SystemFsTypesDefault} for the default value
+   */
+  systemFsTypes: string[];
+
+  /**
+   * On Linux, use the first mount point table in this array that is readable.
+   *
+   * @see {@link LinuxMountTablePathsDefault} for the default values
+   */
+  linuxMountTablePaths: string[];
+
+  /**
+   * Should system volumes be included in result arrays? Defaults to true on
+   * Windows and false elsewhere.
+   */
+  includeSystemVolumes: boolean;
+}

package/src/types/remote_info.ts

@@ -0,0 +1,35 @@
+// src/types/remote_info.ts
+
+/**
+ * Represents remote filesystem information.
+ */
+export interface RemoteInfo {
+  /**
+   * We can sometimes fetch a URI of the resource (like "smb://server/share" or
+   * "file:///media/user/usb")
+   */
+  uri?: string;
+  /**
+   * Protocol used to access the share.
+   */
+  protocol?: string;
+  /**
+   * Does the protocol seem to be a remote filesystem?
+   */
+  remote: boolean;
+  /**
+   * If remote, may include the username used to access the share.
+   *
+   * This will be undefined on NFS and other remote filesystem types that do
+   * authentication out of band.
+   */
+  remoteUser?: string;
+  /**
+   * If remote, the ip or hostname hosting the share (like "rusty" or "10.1.1.3")
+   */
+  remoteHost?: string;
+  /**
+   * If remote, the name of the share (like "homes")
+   */
+  remoteShare?: string;
+}

package/src/types/volume_metadata.ts

@@ -0,0 +1,52 @@
+// src/types/volume_metadata.ts
+
+import type { MountPoint } from "./mount_point.js";
+import type { RemoteInfo } from "./remote_info.js";
+
+/**
+ * Metadata associated to a volume.
+ *
+ * @see https://en.wikipedia.org/wiki/Volume_(computing)
+ */
+export interface VolumeMetadata extends RemoteInfo, MountPoint {
+  /**
+   * The name of the partition
+   */
+  label?: string;
+  /**
+   * Total size in bytes
+   */
+  size?: number;
+  /**
+   * Used size in bytes
+   */
+  used?: number;
+  /**
+   * Available size in bytes
+   */
+  available?: number;
+
+  /**
+   * Path to the device or service that the mountpoint is from.
+   *
+   * Examples include `/dev/sda1`, `nfs-server:/export`,
+   * `//username@remoteHost/remoteShare`, or `//cifs-server/share`.
+   *
+   * May be undefined for remote volumes.
+   */
+  mountFrom?: string;
+
+  /**
+   * The name of the mount. This may match the resolved mountPoint.
+   */
+  mountName?: string;
+
+  /**
+   * UUID for the volume, like "c9b08f6e-b392-11ef-bf19-4b13bb7db4b4".
+   *
+   * On windows, this _may_ be the 128-bit volume UUID, but if that is not
+   * available, like in the case of remote volumes, we fallback to the 32-bit
+   * volume serial number, rendered in lowercase hexadecimal.
+   */
+  uuid?: string;
+}

package/src/unc.ts

@@ -1,7 +1,7 @@
 // src/unc.ts
 
-import { RemoteInfo } from "./remote_info.js";
 import { isBlank, isString } from "./string.js";
+import { RemoteInfo } from "./types/remote_info.js";
 
 /**
  * Checks if a string is formatted as a valid UNC path.

package/src/units.ts

@@ -1,31 +1,63 @@
 // src/units.ts
 
 /**
- * KiB = 1024 bytes
+ * Milliseconds in a second
+ */
+export const SecondMs = 1000;
+
+/**
+ * Milliseconds in a minute
+ */
+export const MinuteMs = 60 * SecondMs;
+
+/**
+ * Milliseconds in an hour
+ */
+export const HourMs = 60 * MinuteMs;
+
+/**
+ * Milliseconds in a day
+ */
+export const DayMs = 24 * HourMs;
+
+/**
+ * Kibibyte (KiB) = 1024 bytes
  * @see https://en.wikipedia.org/wiki/Kibibyte
  */
 export const KiB = 1024;
 
 /**
- * MiB = 1024 KiB
+ * Mebibyte (MiB) = 1024 KiB
  * @see https://en.wikipedia.org/wiki/Mebibyte
  */
 export const MiB = 1024 * KiB;
 
 /**
- * GiB = 1024 MiB
+ * Gibibyte (GiB)= 1024 MiB
  * @see https://en.wikipedia.org/wiki/Gibibyte
  */
 export const GiB = 1024 * MiB;
 
+/**
+ * Tebibyte (TiB) = 1024 GiB
+ *
+ * @see https://en.wikipedia.org/wiki/Byte#Multiple-byte_units
+ */
+export const TiB = 1024 * GiB;
+
+const f = 1023.995 / 1024;
+
 export function fmtBytes(bytes: number): string {
-  if (bytes < KiB) {
+  if (bytes < 1023.5) {
+    bytes = Math.round(bytes);
     return `${bytes} B`;
-  } else if (bytes < MiB) {
+  } else if (bytes < MiB * f) {
     return `${(bytes / KiB).toFixed(2)} KiB`;
-  } else if (bytes < GiB) {
+  } else if (bytes < GiB * f) {
     return `${(bytes / MiB).toFixed(2)} MiB`;
-  } else {
+  } else if (bytes < TiB * f) {
     return `${(bytes / GiB).toFixed(2)} GiB`;
+  } else {
+    return `${(bytes / TiB).toFixed(2)} TiB`;
   }
 }