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.
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
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
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 ittype DesiredFile = { readonly path: RepoPath; readonly sha256: Sha256 };
A generated file the templates give: its path and the SHA-256 of its bytes.
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 ittype DesiredWorktree = {
readonly path: RepoPath;
readonly repo: RepoPath;
readonly branch: BranchName;
};
A worktree the manifest asks for.
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 itfunction describeRefusal(why: RefuseWhy): string
A reason for refusing, as one sentence.
describeSkipfunctionno test imports itfunction describeSkip(why: SkipWhy): string
A reason for skipping, as one sentence.
HostChangetypeno test imports ittype 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.
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
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
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
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
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 ittype 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 ittype 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.
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 ittype Plan = { readonly actions: readonly Action[] };
An ordered list of actions: an ergonex:Plan, a plan in the sense of PROV-O.
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 ittype 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 ittype 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 ittype 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.