IF Commons GitHub

portable

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-workspace-model FR-009

Paths that are valid on Linux, macOS and Windows alike (commons 0002-workspace-model FR-009 to FR-012): segment refuses what one of them would not take, repoPath joins segments, a pair of paths that are one after Unicode normalization and case folding are told apart from the ones that are not, and a path longer than Windows' limit is told as it is.

A segment is refused for: nothing in it, . and ..; <, >, :, ", /, \, |, ?, * and the control characters; a trailing dot or space; a Windows device name (CON, PRN, AUX, NUL, COM0 to COM9, LPT0 to LPT9, with the superscript digits ¹ ² ³ in their place, and CONIN$ and CONOUT$) in any case and with any extension (aux.git is AUX); more than 255 bytes in UTF-8; and a name that is not in Unicode normalization form NFC (a name typed on macOS in NFD would be another name there). Case folding is the upper case then the lower case of the NFC form, which makes Straße and STRASSE one name, as a case-insensitive file system does.

Source: commons/ergonex/src/portable.ts

12 of 17 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

checkPathLengthfunction
function checkPathLength(windowsPath: string, longPathsEnabled: boolean): Result<string, PathTooLong>

Whether a path, written as Windows writes it (C:\Users\a\workspaces\github.com\o\r), may be used: where long paths are not enabled, more than 259 characters are refused with the path named; where they are, no length is refused.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

childfunctionno test imports it
function child(path: RepoPath, name: PortableSegment): RepoPath

A path with one more segment below it.

Collisiontypeno test imports it
type Collision = {
  readonly key: string;
  readonly members: readonly { readonly id: string; readonly path: string }[];
};

Two or more paths that are one after folding, with the name each was given.

collisionsfunction
function collisions(items: readonly { readonly id: string; readonly path: string; }[]): readonly Collision[]

The paths that collide: every group of two or more items whose paths are equal after NFC and case folding (an item listed twice collides with itself), each member named, in the order of the first. id says what the path is for (a repository's remote, a worktree, a generated file).

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

describePortableErrorfunction
function describePortableError(e: PortableError): string

A refusal as one sentence that names the text and what to do.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

foldKeyfunction
function foldKey(path: string): string

The key under which two names are one on a file system that folds case and normalizes Unicode: NFC, upper case, lower case, NFC.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

MAX_SEGMENT_BYTESconst
const MAX_SEGMENT_BYTES: 255

The longest name, in bytes of UTF-8.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

nativePathfunction
function nativePath(root: string, path: RepoPath, separator: "/" | "\\"): string

A path as the operating system writes it below a root: the root, then the segments with the platform's separator.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

PathTooLongtypeno test imports it
type PathTooLong = {
  readonly kind: "path-too-long";
  readonly path: string;
  readonly length: number;
  readonly limit: number;
};

A path that is too long for Windows, as ergonex:Error says it.

PortableErrortypeno test imports it
type PortableError = | { readonly kind: "empty" } | { readonly kind: "dot"; readonly segment: string } | { r… (648 characters)
type PortableError =
  | { readonly kind: "empty" }
  | { readonly kind: "dot"; readonly segment: string }
  | {
      readonly kind: "forbidden-character";
      readonly segment: string;
      readonly character: string;
    }
  | { readonly kind: "control-character"; readonly segment: string }
  | { readonly kind: "trailing-dot-or-space"; readonly segment: string }
  | {
      readonly kind: "device-name";
      readonly segment: string;
      readonly device: string;
    }
  | {
      readonly kind: "too-long";
      readonly segment: string;
      readonly bytes: number;
    }
  | { readonly kind: "not-nfc"; readonly segment: string };

Why a text is not a portable path segment.

REPO_PATH_ROOMconst
const REPO_PATH_ROOM: 150

The most characters of a repository's own path (the root and the repository's path under it) that leaves room for the files inside it (0002-workspace-model FR-048).

Imported by 2 tests of the run (2 passed, 0 failed): the library's results

repoPathfunction
function repoPath(segments: readonly string[]): Result<RepoPath, PortableError>

Segments as a path of the workspace, each made by segment, with / between them; the first refusal otherwise. At least one segment.

Imported by 45 tests of the run (45 passed, 0 failed): the library's results

RepoPathLengthtypeno test imports it
type RepoPathLength =
  | { readonly kind: "fits"; readonly length: number }
  | { readonly kind: "no-room"; readonly length: number }
  | { readonly kind: "too-long"; readonly length: number };

How a repository's own path stands against the two limits of FR-048.

repoPathLengthfunction
function repoPathLength(root: string, path: RepoPath, separator: "/" | "\\"): RepoPathLength

A repository's own path, as the system writes it below the root (separator is \\ on Windows and / elsewhere), against the limits of FR-048: up to 150 characters it fits; over 150 it leaves no room for the files inside it; over 259 it is too long, whether or not long paths are enabled, because tools that work with a path do not all take a long one.

Imported by 2 tests of the run (2 passed, 0 failed): the library's results

segmentfunction
function segment(text: string): Result<PortableSegment, PortableError>

A text as a path segment valid on every operating system, or why not.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

segmentsOffunction
function segmentsOf(path: RepoPath): readonly PortableSegment[]

The segments of a path of the workspace.

Imported by 9 tests of the run (9 passed, 0 failed): the library's results

WINDOWS_PATH_LIMITconst
const WINDOWS_PATH_LIMIT: 259

The most characters a path may have on Windows while long paths are off: 259, as the limit of 260 counts the terminating character.

Imported by 11 tests of the run (11 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.