|
| 1 | +/** |
| 2 | + * `<Git.Switch>` — put the contextual checkout on a named branch |
| 3 | + * (specs/workflow-workspace-spec.md §7.1). |
| 4 | + * |
| 5 | + * ```md |
| 6 | + * <Repository name="project" url={props.repository}> |
| 7 | + * <Git.Switch branch="release/1.4" base="main" /> |
| 8 | + * </Repository> |
| 9 | + * ``` |
| 10 | + * |
| 11 | + * There is no path prop, and there is no repository prop. Which checkout this |
| 12 | + * moves is decided by where it is written: the enclosing `<Repository>` names |
| 13 | + * the repository, and the contextual working directory names the checkout |
| 14 | + * inside it, so the same element inside a `<Dir path={worktree}>` moves that |
| 15 | + * linked worktree instead. Both are observations. This component holds no |
| 16 | + * authority over either, and the installed provider rereads what this run |
| 17 | + * retained rather than believing what it was handed. |
| 18 | + * |
| 19 | + * It renders nothing and binds nothing. A switch is a state change, not a value |
| 20 | + * a later element reads; what the run retains about it is journal evidence |
| 21 | + * rather than something a document could have used, and returning a branch name |
| 22 | + * a document already wrote would only invite reading it back as though it were |
| 23 | + * an answer. |
| 24 | + * |
| 25 | + * Failure policy is `<Repository>`'s. A refusal this recognizes — no Repository |
| 26 | + * in scope, a working directory that is not one of this run's checkouts, a base |
| 27 | + * that names no commit, a branch another checkout holds, local changes Git would |
| 28 | + * overwrite — arrives as a fixed `GitOperationError` and then fails the operation |
| 29 | + * it is part of. An authored `<PrintErrors>` region decides otherwise, for its |
| 30 | + * whole region. A stale-state failure travels past every printing boundary, |
| 31 | + * because retained state disagreeing with what is there is not something the |
| 32 | + * document did. |
| 33 | + */ |
| 34 | + |
| 35 | +import { cwd } from "@executablemd/runtime"; |
| 36 | +import { hasContent } from "@executablemd/core"; |
| 37 | +import type { Operation } from "effection"; |
| 38 | +import type { Json } from "@executablemd/durable-streams"; |
| 39 | +import { GitComposition } from "../git-api.ts"; |
| 40 | +import { currentRepository } from "../context.ts"; |
| 41 | +import { GitOperationError } from "../errors.ts"; |
| 42 | + |
| 43 | +/** The component name, as a document writes it and as a refusal names it. */ |
| 44 | +export const SWITCH = "<Git.Switch>"; |
| 45 | + |
| 46 | +export const props = { |
| 47 | + type: "object", |
| 48 | + properties: { |
| 49 | + branch: { type: "string", minLength: 1 }, |
| 50 | + base: { type: "string", minLength: 1 }, |
| 51 | + }, |
| 52 | + required: ["branch"], |
| 53 | + additionalProperties: false, |
| 54 | +}; |
| 55 | + |
| 56 | +function required(props: Record<string, Json>, prop: string): string { |
| 57 | + const value = props[prop]; |
| 58 | + if (typeof value !== "string" || value === "") { |
| 59 | + throw new GitOperationError( |
| 60 | + SWITCH, |
| 61 | + "invalid-invocation", |
| 62 | + `${SWITCH} needs a non-empty ${prop}.`, |
| 63 | + ); |
| 64 | + } |
| 65 | + return value; |
| 66 | +} |
| 67 | + |
| 68 | +export default function* GitSwitch(props: Record<string, Json>): Operation<string> { |
| 69 | + const branch = required(props, "branch"); |
| 70 | + const base = typeof props.base === "string" && props.base !== "" ? props.base : undefined; |
| 71 | + |
| 72 | + // Content would have nowhere to go: this element renders nothing, so children |
| 73 | + // written inside it would expand into a result nobody reads. Refusing says so |
| 74 | + // where a document can still be corrected. |
| 75 | + if (yield* hasContent()) { |
| 76 | + throw new GitOperationError( |
| 77 | + SWITCH, |
| 78 | + "invalid-invocation", |
| 79 | + `${SWITCH} renders nothing, so it takes no content. Write it as ` + |
| 80 | + `<Git.Switch branch=${JSON.stringify(branch)} />.`, |
| 81 | + ); |
| 82 | + } |
| 83 | + |
| 84 | + const repository = yield* currentRepository(); |
| 85 | + if (repository === undefined) { |
| 86 | + throw new GitOperationError( |
| 87 | + SWITCH, |
| 88 | + "no-repository-context", |
| 89 | + `${SWITCH} is invalid outside a lexical <Repository>: a branch is a branch of one, and ` + |
| 90 | + "there is none in scope here.", |
| 91 | + ); |
| 92 | + } |
| 93 | + |
| 94 | + yield* GitComposition.operations.switchBranch({ |
| 95 | + repositoryName: repository.name, |
| 96 | + checkoutPath: yield* cwd(), |
| 97 | + branch, |
| 98 | + base, |
| 99 | + }); |
| 100 | + return ""; |
| 101 | +} |
0 commit comments