path.gr

/**
 * Utilities for working with system paths.
 *
 * This module treats paths purely as a data representation and does not
 * provide functionality for interacting with the file system.
 *
 * This module explicitly encodes whether a path is absolute or relative, and
 * whether it refers to a file or a directory, as part of the `Path` type.
 *
 * Paths in this module abide by a special POSIX-like representation/grammar
 * rather than one defined by a specific operating system. The rules are as
 * follows:
 *
 * - Path separators are denoted by `/` for POSIX-like paths
 * - Absolute paths may be rooted either at the POSIX-like root `/` or at Windows-like drive roots like `C:/`
 * - Paths referencing files must not include trailing forward slashes, but paths referencing directories may
 * - The path segment `.` indicates the relative "current" directory of a path, and `..` indicates the parent directory of a path
 *
 * @example from "path" include Path
 *
 * @since v0.5.5
 */
module Path

from "string" include String
from "list" include List
from "option" include Option
from "result" include Result
from "char" include Char

// this module is influenced by https://github.com/reasonml/reason-native/blob/a0ddab6ab25237961e32d8732b0a222ec2372d4a/src/fp/Fp.re
// with some modifications; reason-native license:

// MIT License
//
// Copyright (c) Facebook, Inc. and its affiliates.
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.

enum Token {
  Slash,
  Dot,
  Dotdot,
  DriveTok(Char),
  Text(String),
}

enum DirsUp {
  Zero,
  Positive,
}

enum FileType {
  File,
  Dir,
}

// hack to be able to concretely distinguish TypedPath from PathInfo and
// enforce TypedPath's type parameters
record TFileType<a> {
  fileType: FileType,
}

// Rel(Number) represents the number of directories up from the base point
enum rec Base {
  Rel(Number),
  Abs(AbsoluteRoot),
}
and type PathInfo = (Base, FileType, List<String>)
and record TBase<a> {
  base: Base,
}
/**
 * Represents an absolute path's anchor point.
 */
and provide enum AbsoluteRoot {
  Root,
  Drive(Char),
}

// Dummy record names put here just to distinguish the two. These could be
// replaced with opaque types if they get added to the language
/**
 * Represents a relative path.
 */
abstract record Relative {
  _rel: Void,
}

/**
 * Represents an absolute path.
 */
abstract record Absolute {
  _abs: Void,
}

/**
 * Represents a path referencing a file.
 */
abstract record File {
  _file: Void,
}

/**
 * Represents a path referencing a directory.
 */
abstract record Directory {
  _directory: Void,
}

/**
 * Represents a path typed on (`Absolute` or `Relative`) and (`File` or
 * `Directory`)
 */
abstract type rec TypedPath<a, b> = (TBase<a>, TFileType<b>, List<String>)
/**
 * Represents a system path.
 */
and provide enum Path {
  AbsoluteFile(TypedPath<Absolute, File>),
  AbsoluteDir(TypedPath<Absolute, Directory>),
  RelativeFile(TypedPath<Relative, File>),
  RelativeDir(TypedPath<Relative, Directory>),
}

/**
 * Represents a platform-specific path encoding scheme.
 */
provide enum Platform {
  Windows,
  Posix,
}

/**
 * Represents an error that can occur when finding a property of a path.
 */
provide enum PathOperationError {
  IncompatiblePathType,
}

/**
 * Represents an error that can occur when appending paths.
 */
provide enum AppendError {
  AppendToFile,
  AppendAbsolute,
}

/**
 * Represents the status of an ancestry check between two paths.
 */
provide enum AncestryStatus {
  Descendant,
  Ancestor,
  Self,
  NoLineage,
}

/**
 * Represents an error that can occur when the types of paths are incompatible
 * for an operation.
 */
provide enum IncompatibilityError {
  DifferentRoots,
  DifferentBases,
}

/**
 * Represents possible errors for the `relativeTo` operation.
 */
provide enum RelativizationError {
  Incompatible(IncompatibilityError),
  ImpossibleRelativization,
}

let makeToken = str => {
  match (str) {
    "." => Dot,
    ".." => Dotdot,
    _ when String.length(str) == 2 && String.charAt(1, str) == ':' =>
      DriveTok(String.charAt(0, str)),
    _ => Text(str),
  }
}

let parseNextToken = (path: PathInfo, nextToken) => {
  let (base, ft, subs) = path
  match (nextToken) {
    Slash | Dot => path,
    DriveTok(label) => (base, ft, [Char.toString(label) ++ ":", ...subs]),
    Text(str) => (base, ft, [str, ...subs]),
    Dotdot => {
      match (path) {
        (_, _, [_, ...rest]) => (base, ft, rest),
        (Rel(upDirs), _, []) => (Rel(upDirs + 1), ft, []),
        (Abs(_), _, []) => path,
      }
    },
  }
}

// splits a path on forward slashes
let lexPath = (pathStr, platform) => {
  let isSeparator = char => {
    char == '/' || platform == Windows && char == '\\'
  }
  let len = String.length(pathStr)
  let mut revTokens = []
  let mut segBeginI = 0
  for (let mut i = 0; i < len; i += 1) {
    if (isSeparator(String.charAt(i, pathStr))) {
      if (segBeginI != i) {
        let tok = makeToken(String.slice(segBeginI, end=i, pathStr))
        revTokens = [tok, ...revTokens]
      }
      revTokens = [Slash, ...revTokens]
      segBeginI = i + 1
    }
  }
  if (segBeginI < len) {
    let lastPart = String.slice(segBeginI, end=len, pathStr)
    revTokens = [makeToken(lastPart), ...revTokens]
  }
  List.reverse(revTokens)
}

let isFilePath = tokens => {
  let revTokens = List.reverse(tokens)
  match (revTokens) {
    [Dot | Dotdot | Slash, ..._] => false,
    _ => true,
  }
}

// utility functions to translate path types

let toTyped = (pathInfo: PathInfo) => {
  let (base, fileType, subs) = pathInfo
  ({ base, }, { fileType, }, subs): TypedPath<a, b>
}

let toUntyped = (typedPath: TypedPath<a, b>) => {
  let (base, fileType, subs) = typedPath
  let { base } = base
  let { fileType } = fileType
  (base, fileType, subs): PathInfo
}

let pathInfo = (path: Path) => {
  match (path) {
    AbsoluteDir(x) => toUntyped(x),
    AbsoluteFile(x) => toUntyped(x),
    RelativeDir(x) => toUntyped(x),
    RelativeFile(x) => toUntyped(x),
  }
}

let toPath = (path: PathInfo) => {
  match (path) {
    (Abs(_), File, _) as p => AbsoluteFile(toTyped(p)),
    (Abs(_), Dir, _) as p => AbsoluteDir(toTyped(p)),
    (Rel(_), File, _) as p => RelativeFile(toTyped(p)),
    (Rel(_), Dir, _) as p => RelativeDir(toTyped(p)),
  }
}

let parseAbs = (tokens, fileType) => {
  match (tokens) {
    [] => None,
    [first, ...rest] as tokens => {
      if (fileType == File && !isFilePath(tokens)) {
        None
      } else {
        let init = match (first) {
          Slash => Some((Abs(Root), fileType, [])),
          DriveTok(label) => Some((Abs(Drive(label)), fileType, [])),
          _ => None,
        }
        Option.map(init => List.reduce(parseNextToken, init, rest), init)
      }
    },
  }
}

// TODO(#1496): provide these functions once module system added

let absoluteFile = tokens => {
  let pathOpt = parseAbs(tokens, File)
  Option.map(toTyped, pathOpt): Option<TypedPath<Absolute, File>>
}

let absoluteDir = tokens => {
  let pathOpt = parseAbs(tokens, Dir)
  Option.map(toTyped, pathOpt): Option<TypedPath<Absolute, Directory>>
}

let parseRel = (tokens, fileType) => {
  let (first, rest) = match (tokens) {
    [] => (Dot, []),
    [first, ...rest] => (first, rest),
  }
  let tokens = [first, ...rest]

  if (fileType == File && !isFilePath(tokens)) {
    None
  } else {
    let init = match (first) {
      Dot => Some((Rel(0), fileType, [])),
      Dotdot => Some((Rel(1), fileType, [])),
      Text(str) => Some((Rel(0), fileType, [str])),
      _ => None,
    }
    Option.map(init => List.reduce(parseNextToken, init, rest), init)
  }
}

let relativeFile = tokens => {
  let pathOpt = parseRel(tokens, File)
  Option.map(toTyped, pathOpt): Option<TypedPath<Relative, File>>
}

let relativeDir = tokens => {
  let pathOpt = parseRel(tokens, Dir)
  Option.map(toTyped, pathOpt): Option<TypedPath<Relative, Directory>>
}

// TODO(#1496): reuse this and the other helper functions for the typed implementations
let fromStringHelper = (pathStr, platform) => {
  let tokens = match (lexPath(pathStr, platform)) {
    // will cause empty strings to get parsed as relative directory '.'
    [] => [Dot],
    tokens => tokens,
  }
  let isAbs = match (tokens) {
    [Slash | DriveTok(_), ..._] => true,
    _ => false,
  }
  let isDir = !isFilePath(tokens)

  let path = (mkPath, pathType) => {
    Option.expect("Impossible: failed parse of " ++ pathType, mkPath(tokens))
  }

  match ((isAbs, isDir)) {
    (true, true) => AbsoluteDir(path(absoluteDir, "absolute dir")),
    (true, false) => AbsoluteFile(path(absoluteFile, "absolute file")),
    (false, true) => RelativeDir(path(relativeDir, "relative dir")),
    (false, false) => RelativeFile(path(relativeFile, "relative file")),
  }
}

/**
 * Parses a path string into a `Path` using the path separators appropriate to
 * the given platform (`/` for `Posix` and either `/` or `\` for `Windows`).
 * Paths will be parsed as file paths rather than directory paths if there is
 * ambiguity.
 *
 * @param pathStr: The string to parse as a path
 * @param platform: The platform whose path separators should be used for parsing
 * @returns The path wrapped with details encoded within the type
 *
 * @example fromString("file.txt") // a relative Path referencing the file ./file.txt
 * @example fromString(".") // a relative Path referencing the current directory
 * @example fromString("/bin/", Posix) // an absolute Path referencing the directory /bin/
 * @example fromString("C:\\file.txt", Windows) // a relative Path referencing the file C:\file.txt
 *
 * @since v0.5.5
 * @history v0.6.0: Merged with `fromPlatformString`; modified signature to accept platform
 */
provide let fromString = (pathStr, platform=Posix) => {
  fromStringHelper(pathStr, platform)
}

let toStringHelper = (path, platform) => {
  let (base, fileType, revSegs) = path
  let sep = match (platform) {
    Windows => "\\",
    Posix => "/",
  }
  let segs = List.reverse(revSegs)
  let segs = match (base) {
    Abs(absFrom) => {
      let prefix = match (absFrom) {
        Root => "",
        Drive(label) => Char.toString(label) ++ ":",
      }
      [prefix, ...segs]
    },
    Rel(upDirs) => {
      let goUp = List.init(upDirs, (_) => "..")
      if (goUp != []) List.append(goUp, segs) else [".", ...segs]
    },
  }
  let segs = match (fileType) {
    File => segs,
    Dir => List.append(segs, [""]),
  }
  List.join(sep, segs)
}

/**
 * Converts the given `Path` into a string, using the canonical path separator
 * appropriate to the given platform (`/` for `Posix` and `\` for `Windows`).
 * A trailing slash is added to directory paths.
 *
 * @param path: The path to convert to a string
 * @param platform: The `Platform` to use to represent the path as a string
 * @returns A string representing the given path
 *
 * @example toString(fromString("/file.txt")) == "/file.txt"
 * @example toString(fromString("dir/"), Posix) == "./dir/"
 * @example toString(fromString("C:/file.txt"), Windows) == "C:\\file.txt"
 *
 * @since v0.5.5
 * @history v0.6.0: Merged with `toPlatformString`; modified signature to accept platform
 */
provide let toString = (path, platform=Posix) => {
  toStringHelper(pathInfo(path), platform)
}

/**
 * Determines whether the path is a directory path.
 *
 * @param path: The path to inspect
 * @returns `true` if the path is a directory path or `false` otherwise
 *
 * @example isDirectory(fromString("file.txt")) == false
 * @example isDirectory(fromString("/bin/")) == true
 *
 * @since v0.5.5
 */
provide let isDirectory = path => {
  let (_, fileType, _) = pathInfo(path)
  fileType == Dir
}

/**
 * Determines whether the path is an absolute path.
 *
 * @param path: The path to inspect
 * @returns `true` if the path is absolute or `false` otherwise
 *
 * @example isAbsolute(fromString("/Users/me")) == true
 * @example isAbsolute(fromString("./file.txt")) == false
 */
provide let isAbsolute = path => {
  let (base, _, _) = pathInfo(path)
  match (base) {
    Abs(_) => true,
    _ => false,
  }
}

// should only be used on relative path appended to directory path
let rec appendHelper = (path: PathInfo, toAppend: PathInfo) =>
  match (toAppend) {
    (Rel(up2), ft, s2) => match (path) {
      (Rel(up1), _, []) => (Rel(up1 + up2), ft, s2),
      (Abs(_) as d, _, []) => (d, ft, s2),
      (d, pft, [_, ...rest] as s1) => {
        if (up2 > 0)
          appendHelper((d, pft, rest), (Rel(up2 - 1), ft, s2))
        else
          (d, ft, List.append(s2, s1))
      },
    },
    (Abs(_), _, _) => fail "Impossible: relative path encoded as absolute path",
  }: PathInfo

/**
 * Creates a new path by appending a relative path segment to a directory path.
 *
 * @param path: The base path
 * @param toAppend: The relative path to append
 * @returns `Ok(path)` combining the base and appended paths or `Err(err)` if the paths are incompatible
 *
 * @example append(fromString("./dir/"), fromString("file.txt")) == Ok(fromString("./dir/file.txt"))
 * @example append(fromString("a.txt"), fromString("b.sh")) == Err(AppendToFile) // cannot append to file path
 * @example append(fromString("./dir/"), fromString("/dir2")) == Err(AppendAbsolute) // cannot append an absolute path
 *
 * @since v0.5.5
 */
provide let append = (path: Path, toAppend: Path) => {
  match ((pathInfo(path), pathInfo(toAppend))) {
    ((_, File, _), _) => Err(AppendToFile),
    (_, (Abs(_), _, _)) => Err(AppendAbsolute),
    (pathInfo1, pathInfo2) => Ok(toPath(appendHelper(pathInfo1, pathInfo2))),
  }
}

let dirsUp = x => if (x == 0) Zero else Positive

// helper function for relativizing paths; handles the correct number of
// directories to "go up" from one path to another
let rec relativizeDepth = ((up1, s1), (up2, s2)) =>
  match ((dirsUp(up1), dirsUp(up2), s1, s2)) {
    (Zero, Zero, [hd1, ...tl1], [hd2, ...tl2]) when hd1 == hd2 =>
      relativizeDepth((0, tl1), (0, tl2)),
    (Zero, Zero, [], _) => Ok((up2, s2)),
    (Zero, Zero, _, _) => Ok((List.length(s1), s2)),
    (Positive, Positive, _, _) => relativizeDepth((up1 - 1, s1), (up2 - 1, s2)),
    (Zero, Positive, _, _) => Ok((List.length(s1) + up2, s2)),
    (Positive, Zero, _, _) => Err(ImpossibleRelativization),
  }

let relativeToHelper = (source: PathInfo, dest: PathInfo) => {
  // first branch handles special case of two identical file paths; to return
  // '../<name>' instead of '.' (a directory path) because the result file type
  // is expected to be the same as the second arg
  let result = match ((source, dest)) {
    ((_, File, [name, ..._]), _) when source == dest => Ok((1, [name])),
    ((Abs(r1), _, s1), (Abs(r2), _, s2)) =>
      if (r1 != r2)
        Err(Incompatible(DifferentRoots))
      else
        relativizeDepth((0, List.reverse(s1)), (0, List.reverse(s2))),
    ((Rel(up1), _, s1), (Rel(up2), _, s2)) =>
      relativizeDepth((up1, List.reverse(s1)), (up2, List.reverse(s2))),
    _ => fail "Impossible: paths should have both been absolute or relative",
  }

  let (_, fileType, _) = dest
  match (result) {
    Ok((depth, segs)) => Ok((Rel(depth), fileType, List.reverse(segs))),
    Err(err) => Err(err),
  }: Result<PathInfo, RelativizationError>
}

/**
 * Attempts to construct a new relative path which will lead to the destination
 * path from the source path.
 *
 * If the source and destination are incompatible in their bases, the result
 * will be `Err(IncompatibilityError)`.
 *
 * If the route to the destination cannot be concretely determined from the
 * source, the result will be `Err(ImpossibleRelativization)`.
 *
 * @param source: The source path
 * @param dest: The destination path to resolve
 * @returns `Ok(path)` containing the relative path if successfully resolved or `Err(err)` otherwise
 *
 * @example relativeTo(fromString("/usr"), fromString("/usr/bin")) == Ok(fromString("./bin"))
 * @example relativeTo(fromString("/home/me"), fromString("/home/me")) == Ok(fromString("."))
 * @example relativeTo(fromString("/file.txt"), fromString("/etc/")) == Ok(fromString("../etc/"))
 * @example relativeTo(fromString(".."), fromString("../../thing")) Ok(fromString("../thing"))
 * @example relativeTo(fromString("/usr/bin"), fromString("C:/Users")) == Err(Incompatible(DifferentRoots))
 * @example relativeTo(fromString("../here"), fromString("./there")) == Err(ImpossibleRelativization)
 *
 * @since v0.5.5
 */
provide let relativeTo = (source, dest) => {
  let pathInfo1 = pathInfo(source)
  let (base1, _, _) = pathInfo1
  let pathInfo2 = pathInfo(dest)
  let (base2, _, _) = pathInfo2
  match ((base1, base2)) {
    (Abs(_), Rel(_)) | (Rel(_), Abs(_)) => Err(Incompatible(DifferentBases)),
    _ => Result.map(toPath, relativeToHelper(pathInfo1, pathInfo2)),
  }
}

let rec segsAncestry = (baseSegs, pathSegs) => match ((baseSegs, pathSegs)) {
  ([], []) => Self,
  ([], _) => Descendant,
  (_, []) => Ancestor,
  ([first1, ..._], [first2, ..._]) when first1 != first2 => NoLineage,
  ([_, ...rest1], [_, ...rest2]) => segsAncestry(rest1, rest2),
}

// should be used on paths with same absolute/relativeness
let ancestryHelper = (base: PathInfo, path: PathInfo) => {
  let (b1, _, s1) = base
  let (b2, _, s2) = path
  match ((b1, b2)) {
    (Abs(d1), Abs(d2)) when d1 != d2 => Err(DifferentRoots),
    _ => Ok(segsAncestry(List.reverse(s1), List.reverse(s2))),
  }
}

/**
 * Determines the relative ancestry betwen two paths.
 *
 * @param base: The first path to consider
 * @param path: The second path to consider
 * @returns `Ok(ancestryStatus)` with the relative ancestry between the paths if they are compatible or `Err(err)` if they are incompatible
 *
 * @example ancestry(fromString("/usr"), fromString("/usr/bin/bash")) == Ok(Ancestor)
 * @example ancestry(fromString("/Users/me"), fromString("/Users")) == Ok(Descendant)
 * @example ancestry(fromString("/usr"), fromString("/etc")) == Ok(Neither)
 * @example ancestry(fromString("C:/dir1"), fromString("/dir2")) == Err(DifferentRoots)
 *
 * @since v0.5.5
 */
provide let ancestry = (base: Path, path: Path) => {
  let pathInfo1 = pathInfo(base)
  let (base1, _, _) = pathInfo1
  let pathInfo2 = pathInfo(path)
  let (base2, _, _) = pathInfo2
  match ((base1, base2)) {
    (Rel(_), Abs(_)) | (Abs(_), Rel(_)) => Err(DifferentBases),
    _ => ancestryHelper(pathInfo1, pathInfo2),
  }
}

let parentHelper = (path: PathInfo) => match (path) {
  (base, _, [_, ...rest]) => (base, Dir, rest),
  (Rel(upDirs), _, []) => (Rel(upDirs + 1), Dir, []),
  (Abs(_) as base, _, []) => (base, Dir, []),
}: PathInfo

/**
 * Retrieves the path corresponding to the parent directory of the given path.
 *
 * @param path: The path to inspect
 * @returns A path corresponding to the parent directory of the given path
 *
 * @example parent(fromString("./dir/inner")) == fromString("./dir/")
 * @example parent(fromString("/")) == fromString("/")
 *
 * @since v0.5.5
 */
provide let parent = (path: Path) => {
  toPath(parentHelper(pathInfo(path)))
}

let basenameHelper = (path: PathInfo) => match (path) {
  (_, _, [name, ..._]) => Some(name),
  _ => None,
}

/**
 * Retrieves the basename (named final segment) of a path.
 *
 * @param path: The path to inspect
 * @returns `Some(path)` containing the basename of the path or `None` if the path does not have one
 *
 * @example basename(fromString("./dir/file.txt")) == Some("file.txt")
 * @example basename(fromString(".."))) == None
 *
 * @since v0.5.5
 */
provide let basename = (path: Path) => {
  basenameHelper(pathInfo(path))
}

// should only be used on file paths
let stemExtHelper = (path: PathInfo) => match (path) {
  (_, _, [name, ..._]) => {
    // trim first character (which is possibly a .) off as trick for
    // splitting .a.b.c into .a, .b.c
    match (String.indexOf(".", String.slice(1, name))) {
      Some(dotI) => {
        let dotI = dotI + 1
        (String.slice(0, end=dotI, name), String.slice(dotI, name))
      },
      None => (name, ""),
    }
  },
  _ => ("", ""),
}

/**
 * Retrieves the basename of a file path without the extension.
 *
 * @param path: The path to inspect
 * @returns `Ok(path)` containing the stem of the file path or `Err(err)` if the path is a directory path
 *
 * @example stem(fromString("file.txt")) == Ok("file")
 * @example stem(fromString(".gitignore")) == Ok(".gitignore")
 * @example stem(fromString(".a.tar.gz")) == Ok(".a")
 * @example stem(fromString("/dir/")) == Err(IncompatiblePathType) // can only take stem of a file path
 *
 * @since v0.5.5
 */
provide let stem = (path: Path) => {
  match (pathInfo(path)) {
    (_, Dir, _) => Err(IncompatiblePathType),
    pathInfo => {
      let (stem, _) = stemExtHelper(pathInfo)
      Ok(stem)
    },
  }
}

/**
 * Retrieves the extension on the basename of a file path.
 *
 * @param path: The path to inspect
 * @returns `Ok(path)` containing the extension of the file path or `Err(err)` if the path is a directory path
 *
 * @example extension(fromString("file.txt")) == Ok(".txt")
 * @example extension(fromString(".gitignore")) == Ok("")
 * @example extension(fromString(".a.tar.gz")) == Ok(".tar.gz")
 * @example extension(fromString("/dir/")) == Err(IncompatiblePathType) // can only take extension of a file path
 *
 * @since v0.5.5
 */
provide let extension = (path: Path) => {
  match (pathInfo(path)) {
    (_, Dir, _) => Err(IncompatiblePathType),
    pathInfo => {
      let (_, ext) = stemExtHelper(pathInfo)
      Ok(ext)
    },
  }
}

// should only be used on absolute paths
let rootHelper = (path: PathInfo) => match (path) {
  (Abs(root), _, _) => root,
  _ => fail "Impossible: malformed absolute path data",
}

/**
 * Retrieves the root of the absolute path.
 *
 * @param path: The path to inspect
 * @returns `Ok(root)` containing the root of the path or `Err(err)` if the path is a relative path
 *
 * @example root(fromString("C:/Users/me/")) == Ok(Drive('C'))
 * @example root(fromString("/home/me/")) == Ok(Root)
 * @example root(fromString("./file.txt")) == Err(IncompatiblePathType)
 *
 * @since v0.5.5
 */
provide let root = (path: Path) => {
  match (pathInfo(path)) {
    (Rel(_), _, _) => Err(IncompatiblePathType),
    pathInfo => Ok(rootHelper(pathInfo)),
  }
}