Minga.Project.Root (Minga v0.1.0)

Identifies the kind and authorization of a project root.

Recursive project features accept only explicit directory roots. Broad roots such as the user's home directory, the filesystem root, and mounted-volume roots additionally require confirmation from the user flow that created the value. Directory paths are canonicalized so symlink aliases cannot bypass that boundary.

Summary

Types

canonical_error()

Why a filesystem path could not be canonicalized.

error()

Why a root cannot authorize recursive project behavior.

file_error()

Why a workspace-relative file path could not be authorized.

kind()

The filesystem object represented by a root.

t()

A project root with explicit kind and broad-root authorization.

Functions

broad_path?(path)

Returns true when a path names a root whose recursive traversal needs explicit confirmation.

canonical_path(path)

Returns the canonical target of an existing filesystem path.

directory(path, opts \\ [])

Builds an explicit directory workspace root.

file(path)

Builds a file-scoped root that cannot authorize recursive inventory.

inventory_path(root)

Returns the authorized canonical path for recursive inventory.

resolve_file(root, relative_path)

Resolves an existing workspace-relative path inside an authorized directory root.

Types

canonical_error()

@type canonical_error() :: File.posix() | :too_many_symlinks

Why a filesystem path could not be canonicalized.

error()

@type error() ::
  :not_a_directory
  | :broad_root_confirmation_required
  | :invalid_broad_root_confirmation
  | :not_a_directory_root
  | :root_changed

Why a root cannot authorize recursive project behavior.

file_error()

@type file_error() ::
  error()
  | canonical_error()
  | :absolute_path
  | :parent_traversal
  | :outside_workspace

Why a workspace-relative file path could not be authorized.

kind()

@type kind() :: :file | :directory

The filesystem object represented by a root.

t()

@type t() :: %Minga.Project.Root{
  broad_root_confirmed?: boolean(),
  kind: kind(),
  path: String.t()
}

A project root with explicit kind and broad-root authorization.

Functions

broad_path?(path)

@spec broad_path?(String.t()) :: boolean()

Returns true when a path names a root whose recursive traversal needs explicit confirmation.

canonical_path(path)

@spec canonical_path(String.t()) :: {:ok, String.t()} | {:error, canonical_error()}

Returns the canonical target of an existing filesystem path.

directory(path, opts \\ [])

@spec directory(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, error()}

Builds an explicit directory workspace root.

file(path)

@spec file(String.t()) :: t()

Builds a file-scoped root that cannot authorize recursive inventory.

inventory_path(root)

@spec inventory_path(t()) :: {:ok, String.t()} | {:error, error()}

Returns the authorized canonical path for recursive inventory.

resolve_file(root, relative_path)

@spec resolve_file(t(), String.t()) :: {:ok, String.t()} | {:error, file_error()}

Resolves an existing workspace-relative path inside an authorized directory root.