IF Commons GitHub

state

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

The state of one repository of the workspace (commons 0002-workspace-model FR-022, FR-026, FR-027): a repository is observed as exactly one RepoState, classified by a pure function from the facts a host layer read (what is at the path, its remote, its lock files, whether HEAD is on a branch, whether the tree has changes, how many commits it is ahead of and behind its upstream).

The ten states are the keys of the code list ergonex:RepoState, and the three facts the plan reads of each (its default action, whether it is fast-forwardable, whether it holds local work) are the list's: a test holds these tables equal to the ontology's. The order of the classification is the order of what is most in the way: nothing there, then something that is not a repository, a remote that is not the manifest's, a lock, a detached HEAD, uncommitted changes, then the branch against its upstream (diverged, ahead, behind, clean). A remote is compared as a repository, so a clone over SSH is the same as the manifest's HTTPS; a credential in an observed remote is never kept: the state names the host and the path only.

Source: commons/ergonex/src/state.ts

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

classifyfunction
function classify(facts: RepoFacts, expected: RepoRef): RepoState

The one state a repository is in, from what was read of it and the repository the manifest names at its path.

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

defaultActionOffunction
function defaultActionOf(kind: "Ahead" | "Behind" | "Clean" | "Detached" | "Dirty" | "Diverged" | "Locked" | "Missing" | "NotARepo" | "WrongRemote"): "Clone" | "FastForward" | "Refuse" | "Skip"

The kind of action that is a state's default (ergonex:defaultAction): clone where it is missing, fast-forward where it is behind, refuse where it is on the wrong remote or not a repository, skip otherwise.

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

describeRemotefunctionno test imports it
function describeRemote(remote: string | undefined): string

A remote as it may be said in a finding or a plan: the host and the path, never a credential, (none) where there is no remote and (not a remote of a host) where it is a path or unreadable.

fastForwardablefunction
function fastForwardable(kind: "Ahead" | "Behind" | "Clean" | "Detached" | "Dirty" | "Diverged" | "Locked" | "Missing" | "NotARepo" | "WrongRemote"): boolean

Whether a state may be fast-forwarded (ergonex:fastForwardable): Behind alone (0002-workspace-model FR-026).

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

holdsLocalWorkfunction
function holdsLocalWork(kind: "Ahead" | "Behind" | "Clean" | "Detached" | "Dirty" | "Diverged" | "Locked" | "Missing" | "NotARepo" | "WrongRemote"): boolean

Whether a folder in a state holds work that exists nowhere else (ergonex:holdsLocalWork): every state but Missing, Clean and Behind (FR-027). Such a folder is never deleted.

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

isExpectedRemotefunctionno test imports it
function isExpectedRemote(remote: string | undefined, expected: RepoRef): boolean

Whether an observed remote is the repository the manifest names (the same host and path, whatever the scheme).

REPO_STATE_KINDSconst
const REPO_STATE_KINDS: readonly ("Ahead" | "Behind" | "Clean" | "Detached" | "Dirty" | "Diverged" | "Locked" | "Missing" | "NotARepo" | "WrongRemote")[]

All the keys, in the order of the code list.

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

RepoFactstypeno test imports it
type RepoFacts = | { readonly kind: "absent" } | { readonly kind: "not-a-repository" } | { readonly kind: "r… (877 characters)
type RepoFacts =
  | { readonly kind: "absent" }
  | { readonly kind: "not-a-repository" }
  | {
      readonly kind: "repository";
      /** The URL of the remote `origin`, as Git holds it (it may hold a credential, which is never kept); undefined where there is none. */
      readonly remote: string | undefined;
      /** A Git lock file (`index.lock`, `HEAD.lock`, `shallow.lock`, `config.lock`, a ref's `.lock`) is present. */
      readonly lockFile: boolean;
      /** HEAD is on no branch. */
      readonly detached: boolean;
      /** The working tree has uncommitted or untracked changes. */
      readonly dirty: boolean;
      /** Commits the branch has that its upstream does not (those on no remote, where it has no upstream). */
      readonly ahead: number;
      /** Commits the upstream has that the branch does not. */
      readonly behind: number;
    };

What a host layer read of a path.

RepoStatetype
type RepoState = | { readonly kind: "Missing" } | { readonly kind: "Clean" } | { readonly kind: "Dirty" } | { re… (494 characters)
type RepoState =
  | { readonly kind: "Missing" }
  | { readonly kind: "Clean" }
  | { readonly kind: "Dirty" }
  | { readonly kind: "Ahead"; readonly commits: number }
  | { readonly kind: "Behind"; readonly commits: number }
  | {
      readonly kind: "Diverged";
      readonly ahead: number;
      readonly behind: number;
    }
  | { readonly kind: "Locked" }
  | { readonly kind: "Detached" }
  | { readonly kind: "WrongRemote"; readonly found: string }
  | { readonly kind: "NotARepo" };

The observed state of one repository: exactly one of the ten of ergonex:RepoState.

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

RepoStateKindtype
type RepoStateKind = RepoState["kind"];

The key of a state: the local name of an ergonex:RepoState.

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

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