@photostructure/fs-metadata 0.3.2 → 0.3.3

package/src/mount_point.ts

@@ -1,58 +1,7 @@
 import { isObject } from "./object";
 import { isNotBlank } from "./string";
-import { 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;
-}
+import { MountPoint } from "./types/mount_point";
 
 export function isMountPoint(obj: unknown): obj is MountPoint {
-  if (!isObject(obj)) return false;
-  return "mountPoint" in obj && isNotBlank(obj.mountPoint);
+  return isObject(obj) && "mountPoint" in obj && isNotBlank(obj.mountPoint);
 }

package/src/options.ts

@@ -3,59 +3,7 @@
 import { availableParallelism } from "node:os";
 import { compactValues, isObject } from "./object.js";
 import { isWindows } from "./platform.js";
-
-/**
- * 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;
-}
+import type { Options } from "./types/options.js";
 
 /**
  * Default timeout in milliseconds for {@link Options.timeoutMs}.
@@ -82,6 +30,9 @@ export const SystemPathPatternsDefault = [
   "/run/user/*/gvfs",
   "/snap/**",
   "/sys/**",
+  "/tmp",
+  "/var/tmp",
+  // we aren't including /tmp/**, as some people temporarily mount volumes there, like /tmp/project.
   "**/#snapshot", // Synology and Kubernetes volume snapshots
 
   // windows for linux:

package/src/path.ts

@@ -24,11 +24,18 @@ export function normalizePath(
 export function normalizePosixPath(
   mountPoint: string | undefined,
 ): string | undefined {
-  return isBlank(mountPoint)
-    ? undefined
-    : mountPoint === "/"
-      ? mountPoint
-      : mountPoint.replace(/\/+$/, "");
+  if (isBlank(mountPoint)) return undefined;
+  if (mountPoint === "/") return mountPoint;
+  
+  // Fast path: check last char only if no trailing slash
+  if (mountPoint[mountPoint.length - 1] !== "/") return mountPoint;
+  
+  // Slower path: trim trailing slashes
+  let end = mountPoint.length - 1;
+  while (end > 0 && mountPoint[end] === "/") {
+    end--;
+  }
+  return mountPoint.slice(0, end + 1);
 }
 
 /**

package/src/platform.ts

@@ -1,9 +1,9 @@
 // src/platform.ts
 
-import { platform } from "node:os";
+import { arch, platform } from "node:process";
 
-const p = platform();
+export const isLinux = platform === "linux";
+export const isWindows = platform === "win32";
+export const isMacOS = platform === "darwin";
 
-export const isLinux = p === "linux";
-export const isWindows = p === "win32";
-export const isMacOS = p === "darwin";
+export const isArm = isLinux && arch.startsWith("arm");

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;
+}