|
| 1 | +/** |
| 2 | + * `<Repository>` — name a Git repository inside the run's Workspace |
| 3 | + * (specs/workflow-workspace-spec.md §6.1). |
| 4 | + * |
| 5 | + * Two forms, one meaning. Lexical |
| 6 | + * `<Repository name=".." url={..}>…</Repository>` creates or restores the named |
| 7 | + * checkout, then expands its content with that Repository installed as the |
| 8 | + * contextual one and its checkout as the contextual working directory. Both are |
| 9 | + * restored when the invocation ends, on success, failure and cancellation |
| 10 | + * alike, because they live on the invocation's own scope. |
| 11 | + * |
| 12 | + * Self-closing `<Repository name=".." url={..} />` creates or restores the same |
| 13 | + * checkout, renders nothing, and returns the stable Workspace-relative checkout |
| 14 | + * path. Nothing here reaches into how `as` works: the engine's ordinary capture |
| 15 | + * binds the returned string, which is what keeps `as` one rule rather than a |
| 16 | + * Repository-shaped exception to one. |
| 17 | + * |
| 18 | + * ## Who decides what a failure means |
| 19 | + * |
| 20 | + * This component describes what went wrong; it does not decide what the |
| 21 | + * document does about it. A refusal it recognizes — a locator it will not use, |
| 22 | + * a base that names no commit, a name already this run's for another url — |
| 23 | + * arrives as a fixed `RepositoryCompositionError` and then fails the operation |
| 24 | + * it is part of, like any other Effection work. An authored `<PrintErrors>` |
| 25 | + * region is what says otherwise, and it says so for everything inside it rather |
| 26 | + * than for this component alone. |
| 27 | + * |
| 28 | + * Declaring `printErrors` here would have made that decision for every author, |
| 29 | + * for every failure this invocation owns: invalid props, a provider that is not |
| 30 | + * installed, a protocol answer that will not parse. None of those is a refusal |
| 31 | + * a document asked for, and continuing past one would run later siblings as |
| 32 | + * though a checkout existed. |
| 33 | + * |
| 34 | + * Two things are unaffected, in opposite directions. A stale-state failure is a |
| 35 | + * durability failure and travels past every printing boundary, authored or not. |
| 36 | + * A failure of the content a caller projected is the caller's, decided by the |
| 37 | + * region that text is written in. |
| 38 | + */ |
| 39 | + |
| 40 | +import { API } from "@executablemd/runtime"; |
| 41 | +import { content, hasContent } from "@executablemd/core"; |
| 42 | +import type { Operation } from "effection"; |
| 43 | +import type { Json } from "@executablemd/durable-streams"; |
| 44 | +import { RepositoryComposition } from "../api.ts"; |
| 45 | +import { RepositoryContext } from "../context.ts"; |
| 46 | +import { RepositoryCompositionError } from "../errors.ts"; |
| 47 | +import type { RepositoryCreationRequest } from "../records.ts"; |
| 48 | + |
| 49 | +export const props = { |
| 50 | + type: "object", |
| 51 | + properties: { |
| 52 | + name: { type: "string", minLength: 1 }, |
| 53 | + url: { type: "string", minLength: 1 }, |
| 54 | + base: { type: "string", minLength: 1 }, |
| 55 | + }, |
| 56 | + required: ["name", "url"], |
| 57 | + additionalProperties: false, |
| 58 | +}; |
| 59 | + |
| 60 | +function required(props: Record<string, Json>, prop: string): string { |
| 61 | + const value = props[prop]; |
| 62 | + if (typeof value !== "string" || value === "") { |
| 63 | + throw new RepositoryCompositionError( |
| 64 | + typeof props.name === "string" ? props.name : "", |
| 65 | + "invalid-locator", |
| 66 | + `<Repository> needs a non-empty ${prop}.`, |
| 67 | + ); |
| 68 | + } |
| 69 | + return value; |
| 70 | +} |
| 71 | + |
| 72 | +function optional(props: Record<string, Json>, prop: string): string | undefined { |
| 73 | + const value = props[prop]; |
| 74 | + return typeof value === "string" && value !== "" ? value : undefined; |
| 75 | +} |
| 76 | + |
| 77 | +export function parseRepositoryProps(props: Record<string, Json>): RepositoryCreationRequest { |
| 78 | + return { |
| 79 | + name: required(props, "name"), |
| 80 | + locator: required(props, "url"), |
| 81 | + base: optional(props, "base"), |
| 82 | + }; |
| 83 | +} |
| 84 | + |
| 85 | +export default function* Repository(props: Record<string, Json>): Operation<string> { |
| 86 | + const record = yield* RepositoryComposition.operations.createRepository( |
| 87 | + parseRepositoryProps(props), |
| 88 | + ); |
| 89 | + yield* RepositoryComposition.operations.attachRepository(record); |
| 90 | + |
| 91 | + if (!(yield* hasContent())) { |
| 92 | + return record.checkoutPath; |
| 93 | + } |
| 94 | + |
| 95 | + yield* RepositoryContext.around({ current: () => record }, { at: "min" }); |
| 96 | + yield* API.Env.around( |
| 97 | + { |
| 98 | + // deno-lint-ignore require-yield |
| 99 | + *cwd(): Operation<string> { |
| 100 | + return record.checkoutPath; |
| 101 | + }, |
| 102 | + }, |
| 103 | + { at: "min" }, |
| 104 | + ); |
| 105 | + return yield* content(); |
| 106 | +} |
0 commit comments