IF Commons GitHub

plan

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

The plan (commons 0002-workspace-model FR-021 to FR-027, FR-029, FR-030): plan(desired, observed) is a pure function from what the manifest wants and what was observed to an ordered list of actions, each of one of the ten kinds of ergonex:ActionKind. It reads nothing, writes nothing and changes nothing: applying the plan is another layer's work, which observes again before each action.

Fast-forward only: a FastForward is planned for a repository that is Behind and for no other state, and no action of any kind merges, rebases, resets, forces or removes a repository, a worktree or a folder that holds local work: there is no such action, and mayRemove is the guard a layer that removes anything asks first (FR-026, FR-027). A repository in Dirty, Ahead, Diverged, Locked or Detached is skipped with the reason; one on the wrong remote or not a repository is refused, never overwritten. A generated file is written where it is absent or still the bytes the state record holds, and refused where it was edited by hand. A repository has one action for its state (the state's default) and a ConfigureRepo where its local Git configuration differs from the manifest's; a worktree is planned only where another worker or uncommitted work is on the repository (FR-007). A change of the host outside the workspace (ConfigureHost, InstallTool) is in a plan only for ergonex setup (FR-030). The actions are in the order of their paths, folded, so that the same inputs give the same plan.

Source: commons/ergonex/src/plan.ts

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

Actiontype
type Action = | { readonly kind: "Clone"; readonly target: RepoPath; readonly url: string; rea… (1187 characters)
type Action =
  | {
      readonly kind: "Clone";
      readonly target: RepoPath;
      readonly url: string;
      readonly branch?: BranchName | undefined;
    }
  | {
      readonly kind: "FastForward";
      readonly target: RepoPath;
      readonly commits: number;
    }
  | {
      readonly kind: "CreateWorktree";
      readonly target: RepoPath;
      readonly repo: RepoPath;
      readonly branch: BranchName;
    }
  | {
      readonly kind: "ConfigureRepo";
      readonly target: RepoPath;
      readonly settings: Readonly<Record<string, string>>;
    }
  | {
      readonly kind: "ConfigureHost";
      readonly target: string;
      readonly what: string;
    }
  | {
      readonly kind: "WriteGenerated";
      readonly target: RepoPath;
      readonly sha256: Sha256;
    }
  | { readonly kind: "RemoveGenerated"; readonly target: RepoPath }
  | {
      readonly kind: "InstallTool";
      readonly target: string;
      readonly tool: string;
      readonly version: Version;
    }
  | { readonly kind: "Skip"; readonly target: string; readonly why: SkipWhy }
  | {
      readonly kind: "Refuse";
      readonly target: string;
      readonly why: RefuseWhy;
    };

A step of a plan, of one of the ten kinds of ergonex:ActionKind (kind is the key).

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

ActionKindtype
type ActionKind = Action["kind"];

The kind of an action: a key of ergonex:ActionKind.

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

Desiredtype
type Desired = {
  readonly repos: readonly DesiredRepo[];
  readonly worktrees: readonly DesiredWorktree[];
  readonly files: readonly DesiredFile[];
  readonly hostChanges: readonly HostChange[];
};

What the manifest and its templates want.

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

DesiredFiletypeno test imports it
type DesiredFile = { readonly path: RepoPath; readonly sha256: Sha256 };

A generated file the templates give: its path and the SHA-256 of its bytes.

DesiredRepotype
type DesiredRepo = { readonly path: RepoPath; readonly ref: RepoRef; /** The URL it is cloned from, with no creden… (465 characters)
type DesiredRepo = {
  readonly path: RepoPath;
  readonly ref: RepoRef;
  /** The URL it is cloned from, with no credential. */
  readonly cloneUrl: string;
  /** The branch to check out when cloning; the remote's default where absent. */
  readonly branch?: BranchName | undefined;
  /** The local Git configuration the policy wants (`core.hooksPath`, the signing settings, the identity); key to value. */
  readonly settings: Readonly<Record<string, string>>;
};

The repository the manifest names, at its path.

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

DesiredWorktreetypeno test imports it
type DesiredWorktree = {
  readonly path: RepoPath;
  readonly repo: RepoPath;
  readonly branch: BranchName;
};

A worktree the manifest asks for.

describeActionfunction
function describeAction(action: Action): string

An action in words, for a person: what will be done, or why not.

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

describeRefusalfunctionno test imports it
function describeRefusal(why: RefuseWhy): string

A reason for refusing, as one sentence.

describeSkipfunctionno test imports it
function describeSkip(why: SkipWhy): string

A reason for skipping, as one sentence.

HostChangetypeno test imports it
type HostChange =
  | {
      readonly kind: "ConfigureHost";
      readonly target: string;
      readonly what: string;
    }
  | {
      readonly kind: "InstallTool";
      readonly target: string;
      readonly tool: string;
      readonly version: Version;
    };

A change of the host outside the workspace, which only ergonex setup may plan.

isDestructivefunction
function isDestructive(action: "Clone" | "ConfigureHost" | "ConfigureRepo" | "CreateWorktree" | "FastForward" | "InstallTool" | "Refuse" | "RemoveGenerated" | "Skip" | "WriteGenerated" | Action): boolean

Whether an action removes what exists (ergonex:destructive): only RemoveGenerated. It is carried out only where the run says --allow-destructive (FR-029).

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

isHostChangefunction
function isHostChange(action: "Clone" | "ConfigureHost" | "ConfigureRepo" | "CreateWorktree" | "FastForward" | "InstallTool" | "Refuse" | "RemoveGenerated" | "Skip" | "WriteGenerated" | Action): boolean

Whether an action changes the host outside the workspace (ergonex:hostChange): ConfigureHost and InstallTool, which only ergonex setup carries out (FR-030).

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

isSettledfunction
function isSettled(p: Plan): boolean

Whether a plan changes nothing: every action is a Skip (FR-025).

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

mayRemovefunction
function mayRemove(state: RepoState): boolean

Whether a folder in this state may be removed: never one that holds local work (FR-027). A layer that deletes anything asks this first, with a state it has just observed.

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

Observedtype
type Observed = {
  readonly repos: Readonly<Record<string, ObservedRepo>>;
  readonly worktrees: Readonly<Record<string, RepoState>>;
  readonly files: Readonly<Record<string, ObservedFile>>;
};

What was observed of the workspace. A path with no entry is absent.

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

ObservedFiletypeno test imports it
type ObservedFile = {
  readonly onDisk?: Sha256 | undefined;
  readonly recorded?: Sha256 | undefined;
};

What was observed of a generated file: its bytes on disk and the bytes the state record holds; undefined where there is none.

ObservedRepotypeno test imports it
type ObservedRepo = {
  readonly state: RepoState;
  /** Its local Git configuration, key to value (only the keys the policy sets need be here). */
  readonly config: Readonly<Record<string, string>>;
  /** Another person or agent is working in it (its own checkout or another worktree is in use). */
  readonly busy: boolean;
};

What was observed of a repository.

planfunction
function plan(desired: Desired, observed: Observed, options?: PlanOptions): Plan

The plan from what the manifest wants and what was observed. Pure: it reads and writes nothing and never mutates its arguments; the same arguments give the same plan, its actions in the order of their paths (repositories, then worktrees, then generated files, then the changes of the host a setup run may hold).

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

Plantypeno test imports it
type Plan = { readonly actions: readonly Action[] };

An ordered list of actions: an ergonex:Plan, a plan in the sense of PROV-O.

planDigestfunction
function planDigest(p: Plan): Promise<Sha256>

The SHA-256 of a plan: of its actions as JSON, in order. The same plan has the same hash; the evidence of a run names it (0002-workspace-model FR-042).

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

PlanOptionstypeno test imports it
type PlanOptions = {
  /** True only for `ergonex setup`: the only run whose plan may hold a change of the host (FR-030). */
  readonly setupApply?: boolean;
};

What a plan is made under.

RefuseWhytypeno test imports it
type RefuseWhy =
  { readonly kind: "wrong-remote"; readonly found: string } | { readonly kind: "not-a-repository" } | { readonly kind: "generated-edited" };

Why an action is refused.

SkipWhytypeno test imports it
type SkipWhy = | { readonly kind: "in-sync" } | { readonly kind: "uncommitted-changes" } | { readonly kind: "ahead… (547 characters)
type SkipWhy =
  | { readonly kind: "in-sync" }
  | { readonly kind: "uncommitted-changes" }
  | { readonly kind: "ahead"; readonly commits: number }
  | {
      readonly kind: "diverged";
      readonly ahead: number;
      readonly behind: number;
    }
  | { readonly kind: "locked" }
  | { readonly kind: "detached" }
  | { readonly kind: "worktree-unneeded" }
  | { readonly kind: "worktree-exists" }
  | { readonly kind: "base-unavailable"; readonly state: string }
  | { readonly kind: "file-current" }
  | { readonly kind: "file-absent" };

Why an action does nothing.

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