IF Commons GitHub

layout

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

Where things are in the workspace (commons 0002-workspace-model FR-001, FR-006 to FR-008, FR-019, FR-020): a repository is at <home>/<git-host>/<path...>/<repo>, which mirrors its remote; a worktree is at <home>/.worktrees/<git-host>/<path...>/<repo>/<branch-slug>; the path of a remote and the remote of a path are each made from the other; and a name or a depth that would not be valid is refused naming it.

Pure: the root is a value the caller gives (homeOf reads the variable from an environment it is handed, never its own). A host or a segment of a remote named like a folder of the workspace (.worktrees, .ergonex, .git, in any case) is refused (FR-008). A path deeper than two segments below a host without NestedGroups (GitHub, plain Git) is refused with the manager and the path named (FR-020).

Source: commons/ergonex/src/layout.ts

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

describeLayoutErrorfunction
function describeLayoutError(e: LayoutError): string

A refusal as one sentence that names the manager, the path or the name.

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

gitHostOffunction
function gitHostOf(ref: RepoRef): Result<GitHost, LayoutError>

The Git host of a reference as the first folder of its path: lower case, portable, and not named like a folder of the workspace.

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

homeOffunction
function homeOf(facts: HomeFacts): Result<string, HomeError>

The root of the workspace: --home, else $ERGONEX_HOME, else $HOME/workspaces (%USERPROFILE%\workspaces on Windows) (FR-001).

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

HomeErrortypeno test imports it
type HomeError = { readonly kind: "no-home" };

Why no root could be found.

HomeFactstypeno test imports it
type HomeFacts = {
  /** `ERGONEX_HOME`, if set. */
  readonly workspacesHome?: string | undefined;
  /** `HOME` on Linux and macOS, `USERPROFILE` on Windows. */
  readonly home?: string | undefined;
  readonly windows: boolean;
  /** `--home` of this run. */
  readonly override?: string | undefined;
};

What the environment gives of where the workspace is.

LayoutErrortypeno test imports it
type LayoutError = | { readonly kind: "portable"; readonly cause: PortableError } | { readonly kind: "host"; readonl… (492 characters)
type LayoutError =
  | { readonly kind: "portable"; readonly cause: PortableError }
  | { readonly kind: "host"; readonly cause: BrandError }
  | { readonly kind: "workspace-folder"; readonly segment: string }
  | {
      readonly kind: "too-deep";
      readonly manager: HostKind;
      readonly path: readonly string[];
      readonly limit: number;
    }
  | { readonly kind: "too-shallow"; readonly path: readonly string[] }
  | { readonly kind: "not-in-layout"; readonly path: string };

Why a reference or a branch has no place in the workspace.

refOfPathfunction
function refOfPath(path: RepoPath, hostKinds?: Readonly<Record<string, HostKind>>): Result<RepoRef, LayoutError>

The reference a path of the workspace mirrors, the reverse of repoPathOf: its first segment is the host and the kind of host is the manifest's (hostKinds), GitHub for github.com and GitLab for gitlab.com. A path under .worktrees or .ergonex, or of fewer than three segments, is not a repository's.

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

repoPathOffunction
function repoPathOf(ref: RepoRef): Result<RepoPath, LayoutError>

The path of a repository: <git-host>/<path...>/<repo> (FR-006).

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

slugOffunction
function slugOf(text: string): Result<PortableSegment, PortableError>

A branch as one path segment for its worktree: each character Windows would refuse, and /, becomes -, repeated - become one, a trailing dot or space and the dashes at either end are dropped, and a device name gets an underscore after it. feature/x. is feature-x and a:b is a-b; a name that has nothing left is refused.

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

WORKSPACE_FOLDERSconst
const WORKSPACE_FOLDERS: readonly string[]

The folders that belong to the workspace itself, which no host and no segment of a remote may be named like.

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

worktreePathOffunction
function worktreePathOf(ref: RepoRef, branch: string | BranchName): Result<RepoPath, LayoutError>

The path of a worktree of a repository for a branch: .worktrees/<git-host>/<path...>/<repo>/<branch-slug> (FR-007).

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

worktreeWantedfunction
function worktreeWanted(facts: WorktreeFacts): boolean

Whether a worktree is to be made: only where another person or agent, or uncommitted work, is on the repository; otherwise the repository's own checkout is the place to work (FR-007).

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

WorktreeFactstypeno test imports it
type WorktreeFacts = {
  /** The checkout has uncommitted changes (work that a branch change would disturb). */
  readonly uncommittedWork: boolean;
  /** Another person or agent is working in the repository (its own checkout, or another worktree, is in use). */
  readonly otherWorker: boolean;
};

What is known of a repository's checkout when a worktree is asked for.

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