@effected/github-actions 0.1.0 → 0.3.0

package/Artifact.js

@@ -84,9 +84,9 @@ const ARTIFACT_VERSION = 7;
 const azure = {
 	uploadFile: (url, file) => Effect.tryPromise({
 		try: () => new BlockBlobClient(url).uploadFile(file, {
-			blockSize: 64 * 1024 * 1024,
+			blockSize: 67108864,
 			concurrency: 8,
-			maxSingleShotSize: 128 * 1024 * 1024
+			maxSingleShotSize: 134217728
 		}),
 		catch: (cause) => new BlobTransferError({
 			reason: "uploadFailed",

package/BlobStore.githubCache.js

@@ -64,7 +64,8 @@ const fromTwirp = (failure, key) => failure.kind === "status" ? new BlobStoreErr
 });
 const make = (transfer) => Effect.gen(function* () {
 	const http = yield* HttpClient.HttpClient;
-	const backend = resultsBackend(yield* ActionEnvironment).pipe(Effect.mapError((name) => new BlobStoreError({
+	const env = yield* ActionEnvironment;
+	const backend = resultsBackend(env).pipe(Effect.mapError((name) => new BlobStoreError({
 		reason: "misconfigured",
 		detail: `${name} is not set — the Actions results backend is only reachable from a \`uses:\` step, never from \`run:\``
 	})));

package/CacheKey.js

@@ -48,6 +48,20 @@ const MAX_KEY_LENGTH = 512;
 const Segment = Schema.String.check(Schema.isPattern(/^[^,\n\r]+$/));
 const Segments = Schema.NonEmptyArray(Segment).check(Schema.makeFilter((values) => values.join(SEPARATOR).length <= MAX_KEY_LENGTH, { title: `a cache key of at most ${MAX_KEY_LENGTH} characters` }));
 /**
+* One explicit rung: how many leading segments it keeps. The upper bound is
+* cross-field (`segments.length - 1`) and lives on the class schema.
+*/
+const RestoreDepth = Schema.Number.check(Schema.isInt(), Schema.isBetween({
+	minimum: 1,
+	maximum: Number.MAX_SAFE_INTEGER
+}));
+/**
+* The explicit ladder: possibly empty, because **zero rungs is a policy** —
+* exact-match-only restores, spelled by {@link CacheKey.withoutRestoreKeys}.
+* Only *absence* means the default every-prefix ladder.
+*/
+const RestoreDepths = Schema.Array(RestoreDepth);
+/**
 * A GitHub Actions cache key and the restore-key ladder that goes with it.
 *
 * @remarks
@@ -58,6 +72,12 @@ const Segments = Schema.NonEmptyArray(Segment).check(Schema.makeFilter((values)
 * the primary key and its fallbacks impossible to drift apart, which is the
 * failure that produces a cache that never hits and never says why.
 *
+* By default every prefix is a rung. When some segments must never be dropped
+* — a rung without a version digest resurrects stale cross-version caches —
+* give the key an explicit ladder policy with
+* {@link CacheKey.withRestoreDepths}, or none at all with
+* {@link CacheKey.withoutRestoreKeys}, instead of bypassing the typed key.
+*
 * @example
 * ```ts
 * import { CacheKey } from "@effected/github-actions";
@@ -69,9 +89,18 @@ const Segments = Schema.NonEmptyArray(Segment).check(Schema.makeFilter((values)
 *
 * @public
 */
-var CacheKey = class CacheKey extends Schema.Class("CacheKey")({ 
-/** The components, most general first. */
-segments: Segments }) {
+var CacheKey = class CacheKey extends Schema.Class("CacheKey")(Schema.Struct({
+	/** The components, most general first. */
+	segments: Segments,
+	/**
+	* The explicit ladder policy, when one was given: how many leading
+	* segments each rung keeps, in the order the rungs are tried. Absent for
+	* the default every-prefix ladder; **empty for no ladder at all** —
+	* exact-match-only. See {@link CacheKey.withRestoreDepths} and
+	* {@link CacheKey.withoutRestoreKeys}.
+	*/
+	restoreDepths: Schema.optionalKey(RestoreDepths)
+}).check(Schema.makeFilter((key) => key.restoreDepths === void 0 || key.restoreDepths.every((depth) => depth <= key.segments.length - 1) ? void 0 : "every restore depth must be between 1 and segments.length - 1 — a rung keeping every segment would just repeat the primary key"))) {
 	/** The primary key: every segment, joined. */
 	get key() {
 		return this.segments.join(SEPARATOR);
@@ -80,16 +109,85 @@ segments: Segments }) {
 	* The restore keys, most specific first.
 	*
 	* @remarks
-	* Each rung drops the last segment and keeps the trailing separator, so a
-	* three-segment key falls back to two prefixes and a one-segment key falls
-	* back to nothing — there is no rung that would match every cache in the
-	* repository.
+	* By default each rung drops the last segment and keeps the trailing
+	* separator, so a three-segment key falls back to two prefixes and a
+	* one-segment key falls back to nothing — there is no rung that would match
+	* every cache in the repository.
+	*
+	* **The default ladder is every prefix**, which is wrong for a key whose
+	* later segments must never be dropped alone: a
+	* `platform-arch-versionHash-branchHash-lockfileHash` key derives rungs
+	* without the version digest, and those resurrect stale cross-version
+	* caches. A key built with {@link CacheKey.withRestoreDepths} carries its
+	* own ladder instead, and this getter answers exactly that ladder — so
+	* `ActionCache.restore` picks the policy up through the same typed-key
+	* path, no hand-built restore-key list required. An **empty** policy
+	* ({@link CacheKey.withoutRestoreKeys}) answers no rungs at all: only
+	* *absence* selects the default ladder, so "none" is never mistaken for
+	* "every prefix".
 	*/
 	get restoreKeys() {
+		const rung = (length) => `${this.segments.slice(0, length).join(SEPARATOR)}${SEPARATOR}`;
+		if (this.restoreDepths !== void 0) return this.restoreDepths.map(rung);
 		const rungs = [];
-		for (let length = this.segments.length - 1; length >= 1; length -= 1) rungs.push(`${this.segments.slice(0, length).join(SEPARATOR)}${SEPARATOR}`);
+		for (let length = this.segments.length - 1; length >= 1; length -= 1) rungs.push(rung(length));
 		return rungs;
 	}
+	/**
+	* A copy of this key carrying an explicit restore-key ladder policy.
+	*
+	* @remarks
+	* Each depth is the number of **leading segments** the rung keeps, and the
+	* rungs are emitted in exactly the order given — GitHub tries restore keys
+	* in order, so the order IS the policy. Descending depths (most specific
+	* first) are what a fallback ladder almost always wants; that convention is
+	* recommended rather than enforced, because rung ordering is the consumer's
+	* policy where commas, newlines and the length limit are the runner's
+	* protocol. A depth outside `1..segments.length - 1` is refused at
+	* construction: `0` would match every cache in the repository, and
+	* `segments.length` would just repeat the primary key.
+	*
+	* @example
+	* ```ts
+	* import { CacheKey } from "@effected/github-actions";
+	*
+	* const key = CacheKey.of("Linux", "X64", "v1hash", "main", "lockhash").withRestoreDepths([4, 3]);
+	* key.restoreKeys; // ["Linux-X64-v1hash-main-", "Linux-X64-v1hash-"]
+	* ```
+	*/
+	withRestoreDepths(depths) {
+		return CacheKey.make({
+			segments: this.segments,
+			restoreDepths: depths
+		});
+	}
+	/**
+	* A copy of this key that restores from its **exact key only** — no ladder.
+	*
+	* @remarks
+	* The third point in the policy space, and the one the typed key had no
+	* spelling for: absence of a policy means the default every-prefix ladder,
+	* so exact-match-only restores (a cache-bust mode, where a stale partial
+	* hit is worse than a cold start) previously forced the caller back to the
+	* string form. This is the same `restoreDepths` field carrying **zero
+	* rungs** — an honest value, not a sentinel: `ActionCache.restore` sends no
+	* `restore_keys` at all, so the backend answers this key or a miss.
+	*
+	* @example
+	* ```ts
+	* import { CacheKey } from "@effected/github-actions";
+	*
+	* const key = CacheKey.of("Linux", "pnpm-store", "abc123").withoutRestoreKeys();
+	* key.key;          // "Linux-pnpm-store-abc123"
+	* key.restoreKeys;  // []
+	* ```
+	*/
+	withoutRestoreKeys() {
+		return CacheKey.make({
+			segments: this.segments,
+			restoreDepths: []
+		});
+	}
 	/** Build a key from its segments. */
 	static of(...segments) {
 		return CacheKey.make({ segments });

package/CheckDocument.js

@@ -0,0 +1,193 @@
+import { CheckState } from "./CheckState.js";
+import { ManagedDocument } from "./ManagedDocument.js";
+import { Clock, Context, Duration, Effect, Latch, Layer, Ref, Schema, Semaphore } from "effect";
+
+//#region src/CheckDocument.ts
+/**
+* What a run knows about one of its checks: the authoritative state, and the
+* presentation facts a renderer projects into the document.
+*
+* @remarks
+* Only `state` is required. The rest exist because a status table needs them:
+* `title` when the display name differs from the registry key, `outcome` for
+* the one-line verdict cell, `url` for linking the check's name, and `detail`
+* for the per-check block a body region carries. A later report for the same
+* key **replaces** the whole entry — last write wins, per field and per check.
+*
+* @public
+*/
+var CheckReport = class extends Schema.Class("CheckReport")({
+	/** Where the check is now. The last reported state is the authoritative one. */
+	state: CheckState,
+	/** Display name, when it differs from the registry key. */
+	title: Schema.optionalKey(Schema.String),
+	/** A one-line verdict, e.g. `in progress...` or `3 packages ready`. */
+	outcome: Schema.optionalKey(Schema.String),
+	/** A pre-rendered markdown block of per-check detail. */
+	detail: Schema.optionalKey(Schema.String),
+	/** Where the check's name should link. */
+	url: Schema.optionalKey(Schema.String)
+}) {};
+/**
+* Raised when the check document cannot be regenerated or written.
+*
+* @remarks
+* `render` — projecting the registry onto the document failed, almost always
+* because a reported `detail` contains a line the region scanner would read
+* as a marker; the underlying `ManagedDocumentError` rides in `cause`.
+* `sink` — the consumer's write effect failed; its error rides in `cause`.
+* Callers of `flush` branch on `kind`; the background reconciler never fails
+* a fiber with this — it logs and retries on the next report.
+*
+* @public
+*/
+var CheckDocumentError = class extends Schema.TaggedErrorClass()("CheckDocumentError", {
+	/** Which half failed: regenerating the document, or writing it. */
+	kind: Schema.Literals(["render", "sink"]),
+	/** The underlying failure. */
+	cause: Schema.optionalKey(Schema.Defect())
+}) {
+	get message() {
+		return this.kind === "render" ? "The check document could not be regenerated from the reported state" : "Writing the check document failed";
+	}
+};
+/**
+* A living document of check state: an in-process registry the run reports
+* into, debounced onto a marker-delimited document, written through a narrow
+* sink.
+*
+* @remarks
+* **Push, not pull.** The run owns its checks and knows when they resolve;
+* nothing here polls GitHub. Consumers call `report` as states change, and a
+* background fiber projects the registry onto a {@link ManagedDocument} —
+* regions replaced from current state, so a check that resolves many times
+* updates its region in place instead of appending.
+*
+* The debounce is **trailing with a max-wait, never leading**: a burst of
+* reports coalesces into one write carrying the *final* state, and a steady
+* stream still surfaces progress every `maxWait`. A pass that renders
+* byte-identical text issues no write at all.
+*
+* `layer` mints fresh state per call — one layer per document. Bind it to a
+* `const` if two parts of a program must share one registry.
+*
+* @example
+* ```ts
+* import { CheckDocument, CheckReport, GitHubMarkdown } from "@effected/github-actions";
+* import { Effect } from "effect";
+*
+* const layer = CheckDocument.layer({
+*   namespace: "my-action",
+*   key: "release-validation",
+*   render: (checks) => [
+*     [
+*       "header",
+*       GitHubMarkdown.table(
+*         ["Check", "Outcome"],
+*         [...checks].map(([key, check]) => [key, check.outcome ?? check.state]),
+*       ),
+*     ],
+*   ],
+*   sink: (rendered) => Effect.log(rendered),
+* });
+*
+* const program = Effect.gen(function* () {
+*   const doc = yield* CheckDocument;
+*   yield* doc.report("build", CheckReport.make({ state: "running" }));
+*   yield* doc.report("build", CheckReport.make({ state: "pass", outcome: "clean" }));
+*   yield* doc.flush;
+* });
+* ```
+*
+* @public
+*/
+var CheckDocument = class CheckDocument extends Context.Service()("@effected/github-actions/CheckDocument") {
+	/**
+	* The reconciler over one document.
+	*
+	* @remarks
+	* Forks the debounce fiber into the layer's scope and registers a
+	* finalizer that flushes once more on the way out, so the scope closing
+	* mid-window cannot strand the final state. A background pass that fails
+	* logs a structured warning and leaves the registry intact — the next
+	* report retries it; only `flush` surfaces the typed error.
+	*/
+	static layer(options) {
+		return Layer.effect(CheckDocument, Effect.gen(function* () {
+			const quietMillis = Duration.toMillis(options.debounce?.quiet ?? "500 millis");
+			const maxWaitMillis = Math.max(Duration.toMillis(options.debounce?.maxWait ?? "3 seconds"), quietMillis);
+			const checksRef = yield* Ref.make(/* @__PURE__ */ new Map());
+			const writtenRef = yield* Ref.make(options.initial ?? "");
+			const versionRef = yield* Ref.make(0);
+			const signal = yield* Latch.make(false);
+			const gate = yield* Semaphore.make(1);
+			const reconcile = Effect.fn("CheckDocument.reconcile")(function* () {
+				const checks = yield* Ref.get(checksRef);
+				const current = yield* Ref.get(writtenRef);
+				const next = yield* (yield* ManagedDocument.parse({
+					namespace: options.namespace,
+					key: options.key,
+					text: current
+				}).pipe(Effect.mapError((cause) => new CheckDocumentError({
+					kind: "render",
+					cause
+				})))).withRegions(options.render(checks)).pipe(Effect.mapError((cause) => new CheckDocumentError({
+					kind: "render",
+					cause
+				})));
+				if (next.text === current) return;
+				yield* options.sink(next.text).pipe(Effect.timeout(options.sinkTimeout ?? "30 seconds"), Effect.mapError((cause) => new CheckDocumentError({
+					kind: "sink",
+					cause
+				})));
+				yield* Ref.set(writtenRef, next.text);
+			});
+			const flush = gate.withPermits(1)(reconcile());
+			const daemon = Effect.gen(function* () {
+				while (true) {
+					yield* signal.await;
+					yield* signal.close;
+					const start = yield* Clock.currentTimeMillis;
+					let settled = false;
+					while (!settled) {
+						const before = yield* Ref.get(versionRef);
+						yield* Effect.sleep(quietMillis);
+						const after = yield* Ref.get(versionRef);
+						const now = yield* Clock.currentTimeMillis;
+						settled = after === before || now - start >= maxWaitMillis;
+					}
+					yield* flush.pipe(Effect.catch((failure) => Effect.logWarning("CheckDocument reconcile failed; retrying on the next report", { kind: failure.kind })));
+				}
+			});
+			yield* Effect.addFinalizer(() => flush.pipe(Effect.catch((failure) => Effect.logWarning("CheckDocument final flush failed", { kind: failure.kind }))));
+			yield* Effect.forkScoped(daemon);
+			return {
+				report: Effect.fn("CheckDocument.report")(function* (check, entry) {
+					yield* Ref.update(checksRef, (current) => {
+						const next = new Map(current);
+						next.set(check, entry);
+						return next;
+					});
+					yield* Ref.update(versionRef, (count) => count + 1);
+					yield* signal.open;
+				}),
+				checks: Ref.get(checksRef),
+				flush
+			};
+		}));
+	}
+	/** An inert double; unstubbed members die naming themselves. */
+	static makeTest = (overrides = {}) => ({
+		report: overrides.report ?? (() => Effect.sync(() => unstubbed("report"))),
+		checks: overrides.checks ?? Effect.sync(() => unstubbed("checks")),
+		flush: overrides.flush ?? Effect.sync(() => unstubbed("flush"))
+	});
+	/** {@link CheckDocument.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(CheckDocument, CheckDocument.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`CheckDocument.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+
+//#endregion
+export { CheckDocument, CheckDocumentError, CheckReport };

package/CheckState.js

@@ -0,0 +1,75 @@
+import { Schema } from "effect";
+
+//#region src/CheckState.ts
+/**
+* The kit's check-state vocabulary.
+*
+* @remarks
+* Deliberately **wider than GitHub's own check-run conclusions**: `running` is
+* a first-class state rather than the absence of a conclusion, and
+* `user_interaction_required` names a release pipeline waiting on a human. A
+* check's lifecycle is a *sequence* of these states, and only the last one is
+* authoritative — resolution is not a terminal transition, so a check may run
+* `running`, `pass`, `running`, `fail` in order, and that means `fail`.
+*
+* Every state projects onto GitHub's check-run wire vocabulary through
+* {@link projectCheckState}. GitHub's `cancelled` conclusion has no
+* counterpart here on purpose: cancellation is something the runner does *to*
+* a run, not a state a pipeline reports about its own checks.
+*
+* @public
+*/
+const CheckState = Schema.Literals([
+	"running",
+	"pass",
+	"fail",
+	"warn",
+	"user_interaction_required",
+	"skipped",
+	"timeout"
+]);
+/**
+* Project a kit check state onto GitHub's check-run wire vocabulary.
+*
+* @remarks
+* The canonical mapping: `running` is `in_progress`; everything else is
+* `completed` with `pass → success`, `fail → failure`, `warn → neutral`
+* (GitHub has no warning conclusion, and `neutral` is its non-failing,
+* non-success verdict), `user_interaction_required → action_required`,
+* `skipped → skipped` and `timeout → timed_out`.
+*
+* @public
+*/
+const projectCheckState = (state) => {
+	switch (state) {
+		case "running": return { status: "in_progress" };
+		case "pass": return {
+			status: "completed",
+			conclusion: "success"
+		};
+		case "fail": return {
+			status: "completed",
+			conclusion: "failure"
+		};
+		case "warn": return {
+			status: "completed",
+			conclusion: "neutral"
+		};
+		case "user_interaction_required": return {
+			status: "completed",
+			conclusion: "action_required"
+		};
+		case "skipped": return {
+			status: "completed",
+			conclusion: "skipped"
+		};
+		case "timeout": return {
+			status: "completed",
+			conclusion: "timed_out"
+		};
+		default: throw new Error(`Unhandled CheckState: ${String(state)}`);
+	}
+};
+
+//#endregion
+export { CheckState, projectCheckState };

package/GitHubMarkdown.js

@@ -0,0 +1,197 @@
+import { Result, Schema, SchemaAST } from "effect";
+import { Code, Html, InlineCode, Link, List, ListItem, Markdown, Paragraph, Root, Table, TableCell, TableRow } from "@effected/markdown";
+
+//#region src/GitHubMarkdown.ts
+/**
+* A block node whose value passes through the serializer verbatim, which is
+* exactly how a pre-rendered markdown fragment must travel: GFM structure
+* around it is escaped, the fragment itself is not.
+*/
+const passthrough = (value) => Html.make({ value });
+/**
+* Serialize a tree the writer built itself.
+*
+* @remarks
+* `Markdown.stringifyResult` is total over every tree this module can
+* construct — its only failure is the hardening depth cap, which a
+* fixed-shape two-level tree cannot reach — so the impossible arm is a
+* defect, **not** a silent fallback to unescaped string joining. The
+* predecessor's fallback arm is the live table-corruption defect this module
+* exists to delete.
+*/
+const render = (root) => Result.getOrThrow(Markdown.stringifyResult(root)).trimEnd();
+const block = (node) => render(Root.make({ children: [node] }));
+/**
+* The fluent markdown writer for GitHub surfaces — PR comments, check-run
+* summaries, job summaries.
+*
+* @remarks
+* Every member takes **pre-rendered markdown** (links, emphasis, emoji — the
+* caller's fragments pass through verbatim) and returns a `string`, so
+* compositions read as plain string assembly. What the writer owns is the
+* *structure*: wherever a fragment could break the construct around it, the
+* output goes through `@effected/markdown`'s node classes and serializer
+* rather than string joining. A table cell carrying `>=1 || <2` renders with
+* its pipes escaped instead of shifting every column after it; a code block
+* whose content contains a fence gets a longer fence; inline code containing
+* a backtick gets a wider delimiter; a URL containing spaces or parentheses
+* is angle-bracketed.
+*
+* This module is the package's **only** importer of `@effected/markdown` — a
+* structural test pins that, on the same terms as the Azure confinement — so
+* an action that never renders markdown never links the engine.
+*
+* @example
+* ```ts
+* import { GitHubMarkdown } from "@effected/github-actions";
+*
+* const body = [
+*   GitHubMarkdown.heading("Release Validation"),
+*   GitHubMarkdown.table(["Check", "Outcome"], [["build", "✅ passed"]]),
+*   GitHubMarkdown.details("Logs", GitHubMarkdown.codeBlock(log, "text")),
+* ].join("\n\n");
+* ```
+*
+* @public
+*/
+var GitHubMarkdown = class GitHubMarkdown {
+	constructor() {}
+	/**
+	* A GFM table.
+	*
+	* @remarks
+	* Cells are pre-rendered markdown; the serializer escapes the pipes GFM
+	* would otherwise read as column breaks. Rows shorter than the header are
+	* padded with empty cells rather than shifting.
+	*/
+	static table(headers, rows) {
+		const inline = (value) => value.replace(/\r?\n/g, "<br>");
+		const cells = (values) => TableRow.make({ children: Array.from({ length: headers.length }, (_, index) => TableCell.make({ children: [passthrough(inline(values[index] ?? ""))] })) });
+		return block(Table.make({ children: [cells(headers), ...rows.map(cells)] }));
+	}
+	/**
+	* A GFM table whose columns are defined ONCE by a row schema.
+	*
+	* @remarks
+	* The schema is the single authority for the table's shape: column order
+	* is field declaration order, each header is the field's `title`
+	* annotation (fall back: the property name, overridable per column), and
+	* each cell is the field value's **encoded** string form — a branded or
+	* typed field projects through its own codec, so the vocabulary lives
+	* with the schema instead of being respelled at every call site, and a
+	* row can no longer transpose columns because it is a typed object, not
+	* a positional array.
+	*
+	* A field whose encoded side is not a string has no string projection to
+	* borrow; the type of `options` makes its column's `format` — and
+	* therefore `columns` and `options` themselves — required. An absent or
+	* `undefined` optional field renders as an empty cell without consulting
+	* codec or formatter.
+	*
+	* The renderer is a pure value: `render` maps current rows through
+	* {@link GitHubMarkdown.table}, so escaping is inherited and identical
+	* rows produce identical output. Rows are already-decoded values of the
+	* schema's type, so encoding them is total in practice; a value smuggled
+	* past the types throws the codec's `SchemaError` as a defect — same
+	* posture as the serializer arm above, **not** a silent fallback.
+	*
+	* Only string-keyed fields become columns; symbol keys are not
+	* enumerable table columns.
+	*
+	* @example
+	* ```ts
+	* import { GitHubMarkdown } from "@effected/github-actions";
+	* import { Schema } from "effect";
+	*
+	* const CheckRow = Schema.Struct({
+	*   name: Schema.String.annotate({ title: "Check" }),
+	*   outcome: Schema.Literals(["passed", "failed"]),
+	* });
+	* const checks = GitHubMarkdown.tableFor(CheckRow);
+	* const body = checks.render([{ name: "build", outcome: "passed" }]);
+	* ```
+	*/
+	static tableFor(schema, ...options) {
+		const overrides = options[0]?.columns ?? {};
+		const columns = Object.keys(schema.fields).map((key) => {
+			const field = schema.fields[key];
+			const column = overrides[key];
+			const format = column?.format;
+			const encode = format === void 0 ? Schema.encodeSync(field) : void 0;
+			return {
+				key,
+				header: column?.header ?? SchemaAST.resolveTitle(field.ast) ?? key,
+				cell: (value) => value === void 0 ? "" : format !== void 0 ? format(value) : encode?.(value) ?? ""
+			};
+		});
+		const headers = columns.map((column) => column.header);
+		return { render: (rows) => GitHubMarkdown.table(headers, rows.map((row) => columns.map((column) => column.cell(row[column.key])))) };
+	}
+	/** An ATX heading; the level defaults to `2`. */
+	static heading(text, level = 2) {
+		return `${"#".repeat(level)} ${text}`;
+	}
+	/** A link. URLs the destination cannot carry raw are angle-bracketed. */
+	static link(text, url) {
+		return block(Paragraph.make({ children: [Link.make({
+			url,
+			children: [passthrough(text)]
+		})] }));
+	}
+	/** Inline code. Content containing backticks widens the delimiter. */
+	static code(text) {
+		return block(Paragraph.make({ children: [InlineCode.make({ value: text })] }));
+	}
+	/** A fenced code block. Content containing a fence lengthens the fence. */
+	static codeBlock(content, language) {
+		return block(Code.make({
+			value: content,
+			fenceChar: "`",
+			...language === void 0 || language === "" ? {} : { lang: language }
+		}));
+	}
+	/**
+	* A list of pre-rendered markdown items.
+	*
+	* @remarks
+	* A multi-line item is indented onto continuation lines, so it stays part
+	* of its bullet instead of terminating the list.
+	*/
+	static list(items, options) {
+		const ordered = options?.ordered ?? false;
+		return block(List.make({
+			ordered,
+			...ordered ? { start: 1 } : {},
+			children: items.map((item) => ListItem.make({ children: [passthrough(item)] }))
+		}));
+	}
+	/**
+	* A collapsible `<details>` block.
+	*
+	* @remarks
+	* mdast has no details node, so this is the one construct the writer emits
+	* as raw HTML. The blank lines around `body` are what make GitHub render
+	* the markdown inside it; `summary` is HTML context — markdown is **not**
+	* rendered there, so bold a summary with `<strong>`, not `**`.
+	*/
+	static details(summary, body) {
+		return `<details>\n<summary>${summary}</summary>\n\n${body}\n\n</details>`;
+	}
+	/**
+	* Pre-rendered markdown, passed through by name.
+	*
+	* @remarks
+	* The identity function, deliberately: every writer member already treats
+	* its fragments as markdown, so `raw` adds no behavior — it adds the
+	* *statement* that a value is already rendered. Use it where a fragment
+	* from elsewhere enters a composition and a reader would otherwise wonder
+	* whether it still needs escaping. It replaces the `Html.make` idiom,
+	* which passes markdown through correctly but announces the wrong intent.
+	*/
+	static raw(markdown) {
+		return markdown;
+	}
+};
+
+//#endregion
+export { GitHubMarkdown };