|
| 1 | +/** |
| 2 | + * `<Worktree>` — a named linked checkout inside the contextual Repository |
| 3 | + * (specs/workflow-workspace-spec.md §6.2). |
| 4 | + * |
| 5 | + * Invalid without an enclosing lexical `<Repository>`. A Worktree exists inside |
| 6 | + * a Repository, and the Repository's name is half of what makes its identity |
| 7 | + * durable across replay; threading that name through props would let a document |
| 8 | + * name a Repository that is not in scope. |
| 9 | + * |
| 10 | + * Its two forms match Repository's. The self-closing form is the one the |
| 11 | + * adversarial workflow uses, because it is the spelling that both binds a path |
| 12 | + * and lets a sibling `<Dir>` render descendants at it: |
| 13 | + * |
| 14 | + * ```md |
| 15 | + * <Repository name="project" url={props.repository}> |
| 16 | + * <Worktree name="implementation" branch={props.branch} as="worktree" /> |
| 17 | + * <Dir path={worktree}>…</Dir> |
| 18 | + * </Repository> |
| 19 | + * ``` |
| 20 | + * |
| 21 | + * A lexical Worktree written with `as` keeps ordinary generic semantics: its |
| 22 | + * rendered descendants are captured and suppressed. It does not bind the |
| 23 | + * checkout path while also rendering them, and nothing here makes an exception |
| 24 | + * so that it could. |
| 25 | + * |
| 26 | + * Failure policy is `<Repository>`'s, for the same reason: a refusal this |
| 27 | + * recognizes — no Repository in scope, a branch another checkout holds, a name |
| 28 | + * already this Repository's for another branch — is described with a fixed |
| 29 | + * `WorktreeCompositionError` and then fails the operation it is part of. An |
| 30 | + * authored `<PrintErrors>` region decides otherwise, for its whole region. |
| 31 | + */ |
| 32 | + |
| 33 | +import { API } from "@executablemd/runtime"; |
| 34 | +import { content, hasContent } from "@executablemd/core"; |
| 35 | +import type { Operation } from "effection"; |
| 36 | +import type { Json } from "@executablemd/durable-streams"; |
| 37 | +import { RepositoryComposition } from "../api.ts"; |
| 38 | +import { RepositoryContext } from "../context.ts"; |
| 39 | +import { WorktreeCompositionError } from "../errors.ts"; |
| 40 | + |
| 41 | +export const props = { |
| 42 | + type: "object", |
| 43 | + properties: { |
| 44 | + name: { type: "string", minLength: 1 }, |
| 45 | + branch: { type: "string", minLength: 1 }, |
| 46 | + base: { type: "string", minLength: 1 }, |
| 47 | + }, |
| 48 | + required: ["name", "branch"], |
| 49 | + additionalProperties: false, |
| 50 | +}; |
| 51 | + |
| 52 | +function required(props: Record<string, Json>, prop: string): string { |
| 53 | + const value = props[prop]; |
| 54 | + if (typeof value !== "string" || value === "") { |
| 55 | + throw new WorktreeCompositionError( |
| 56 | + typeof props.name === "string" ? props.name : "", |
| 57 | + "no-repository-context", |
| 58 | + `<Worktree> needs a non-empty ${prop}.`, |
| 59 | + ); |
| 60 | + } |
| 61 | + return value; |
| 62 | +} |
| 63 | + |
| 64 | +export default function* Worktree(props: Record<string, Json>): Operation<string> { |
| 65 | + const name = required(props, "name"); |
| 66 | + const branch = required(props, "branch"); |
| 67 | + const base = typeof props.base === "string" && props.base !== "" ? props.base : undefined; |
| 68 | + |
| 69 | + const repository = yield* RepositoryContext.operations.current; |
| 70 | + if (repository === undefined) { |
| 71 | + throw new WorktreeCompositionError( |
| 72 | + name, |
| 73 | + "no-repository-context", |
| 74 | + `<Worktree name=${JSON.stringify(name)}> is invalid outside a lexical <Repository>: a ` + |
| 75 | + "Worktree is a checkout of one, and there is none in scope here.", |
| 76 | + ); |
| 77 | + } |
| 78 | + |
| 79 | + const record = yield* RepositoryComposition.operations.createWorktree({ |
| 80 | + repositoryName: repository.name, |
| 81 | + name, |
| 82 | + branch, |
| 83 | + base, |
| 84 | + }); |
| 85 | + yield* RepositoryComposition.operations.attachWorktree(record); |
| 86 | + |
| 87 | + if (!(yield* hasContent())) { |
| 88 | + return record.checkoutPath; |
| 89 | + } |
| 90 | + |
| 91 | + yield* API.Env.around( |
| 92 | + { |
| 93 | + // deno-lint-ignore require-yield |
| 94 | + *cwd(): Operation<string> { |
| 95 | + return record.checkoutPath; |
| 96 | + }, |
| 97 | + }, |
| 98 | + { at: "min" }, |
| 99 | + ); |
| 100 | + return yield* content(); |
| 101 | +} |
0 commit comments