describeLayoutErrorfunctionfunction describeLayoutError(e: LayoutError): stringA refusal as one sentence that names the manager, the path or the name.
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).
describeLayoutErrorfunctionfunction describeLayoutError(e: LayoutError): stringA refusal as one sentence that names the manager, the path or the name.
gitHostOffunctionfunction 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.
homeOffunctionfunction homeOf(facts: HomeFacts): Result<string, HomeError>The root of the workspace: --home, else $ERGONEX_HOME, else $HOME/workspaces (%USERPROFILE%\workspaces on Windows) (FR-001).
HomeErrortypeno test imports ittype HomeError = { readonly kind: "no-home" };Why no root could be found.
HomeFactstypeno test imports ittype 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 ittype 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.
refOfPathfunctionfunction 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.
repoPathOffunctionfunction repoPathOf(ref: RepoRef): Result<RepoPath, LayoutError>The path of a repository: <git-host>/<path...>/<repo> (FR-006).
slugOffunctionfunction 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.
WORKSPACE_FOLDERSconstconst 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.
worktreePathOffunctionfunction 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).
worktreeWantedfunctionfunction worktreeWanted(facts: WorktreeFacts): booleanWhether 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).
WorktreeFactstypeno test imports ittype 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.