@effected/markdown 0.2.0

package/Markdown.js

@@ -0,0 +1,251 @@
+import { Root } from "./MarkdownNode.js";
+import { isGuardExceeded, isRawMarkdownError } from "./internal/carriers.js";
+import { parseBlocks } from "./internal/blockParser.js";
+import { stringifyTree } from "./internal/stringify.js";
+import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
+import { Effect, Option, Result, Schema, SchemaIssue, SchemaTransformation } from "effect";
+
+//#region src/Markdown.ts
+/**
+* The markdown dialects the parser can be pointed at. `"gfm"` — CommonMark
+* 0.31.2 plus the GitHub extensions (tables, strikethrough, autolink
+* literals, task-list items, footnotes, and the tagfilter's output contract)
+* — is the default; `"commonmark"` opts out of every extension. A dialect is
+* a registry composition in the engine, so widening this union is additive
+* and never changes an existing dialect's behavior.
+*
+* @public
+*/
+const MarkdownDialect = Schema.Literals(["commonmark", "gfm"]);
+/**
+* Options controlling parse behavior: `dialect` (omitted, `"gfm"`) and
+* `frontmatter` (omitted, `false` — capture is opt-in).
+*
+* @remarks
+* Frontmatter capture is OFF by default because it changes how a document
+* opening with `---` parses: CommonMark reads the fence document
+* `---\nfoo: bar\n---` as a thematic break and a setext heading, and that
+* spec-conformant reading must hold unless a consumer opts in. Enabled, the
+* engine captures `---`/`+++`/`---json` blocks at offset 0 into a raw
+* `Frontmatter` head node — decoding it is the frontmatter codec modules'
+* job.
+*
+* @public
+*/
+var MarkdownParseOptions = class extends Schema.Class("MarkdownParseOptions")({
+	dialect: Schema.optionalKey(MarkdownDialect),
+	frontmatter: Schema.optionalKey(Schema.Boolean)
+}) {};
+/**
+* Parse failure: the {@link MarkdownDiagnostic} describing why the document
+* was rejected.
+*
+* @remarks
+* CommonMark has no syntax errors — every string is a valid document — so
+* this error carries only hardening-guard trips (P1: `NestingDepthExceeded`).
+* Recoverable oddities are diagnostics on {@link MarkdownDocument}, not
+* failures. A malformed-looking document parses; a nesting bomb fails here
+* rather than crashing with a `RangeError`.
+*
+* @public
+*/
+var MarkdownParseError = class extends Schema.TaggedErrorClass()("MarkdownParseError", { diagnostic: MarkdownDiagnostic }) {
+	get message() {
+		const { code, line, character, message } = this.diagnostic;
+		return `Markdown parse failed: ${code} at ${line}:${character} ${message}`;
+	}
+};
+/**
+* Stringify failure: the {@link MarkdownDiagnostic} describing why the tree
+* was refused.
+*
+* @remarks
+* Serialization is total over parser-produced trees — the parser cannot
+* produce one that nests past the guard, because parsing it would have been
+* refused first. The only failures here are hardening-guard trips on
+* synthesized or decoded hostile trees, symmetric with
+* {@link MarkdownParseError}'s posture on parse. Stringify has no source
+* text to derive positions from, so the diagnostic's `line`/`character` are
+* `0` and `offset` carries whatever the offending node's position claimed.
+*
+* @public
+*/
+var MarkdownStringifyError = class extends Schema.TaggedErrorClass()("MarkdownStringifyError", { diagnostic: MarkdownDiagnostic }) {
+	get message() {
+		const { code, message } = this.diagnostic;
+		return `Markdown stringify failed: ${code} ${message}`;
+	}
+};
+/**
+* The dialect an options object resolves to. The PUBLIC default — `"gfm"`,
+* a product decision — is spelled exactly once, here. The engine's own
+* `parseBlocks` default is `"commonmark"` and means something different: the
+* base dialect the registries compose on top of. The facade always passes
+* this resolved value explicitly, so the two defaults never interact.
+*/
+const dialectOf = (options) => options?.dialect ?? "gfm";
+/**
+* Whether an options object opts into frontmatter capture. The default —
+* `false`, a P3 ruling — is spelled exactly once, here: capture changes how
+* a `---` at offset 0 parses, so the spec-conformant reading is the default
+* and frontmatter is the consumer's explicit choice.
+*/
+const frontmatterOf = (options) => options?.frontmatter ?? false;
+/**
+* Run the block pass, converting the engine's raw carriers into a typed
+* {@link MarkdownParseError} and letting everything else through as a defect.
+*
+* Shared by {@link Markdown.parseResult} and `MarkdownDocument.parseResult`
+* so the two entry points can never disagree about what is typed and what is
+* a defect.
+*
+* @internal
+*/
+const parsePassResult = (text, options) => {
+	try {
+		return Result.succeed(parseBlocks(text, dialectOf(options), frontmatterOf(options)));
+	} catch (caught) {
+		if (isGuardExceeded(caught)) return Result.fail(new MarkdownParseError({ diagnostic: MarkdownDiagnostic.fromRaw(text, {
+			code: caught.reason,
+			message: caught.message,
+			offset: caught.offset,
+			length: 0
+		}) }));
+		if (isRawMarkdownError(caught)) return Result.fail(new MarkdownParseError({ diagnostic: MarkdownDiagnostic.fromRaw(text, caught.diagnostic) }));
+		throw caught;
+	}
+};
+/**
+* The markdown facade: parse markdown source — GFM by default, CommonMark by
+* option — into an mdast-shaped {@link Root} tree, as a pure `Result` or as
+* an `Effect`.
+*
+* @public
+*/
+var Markdown = class Markdown {
+	/**
+	* Parse markdown into a {@link Root} tree, synchronously, as a `Result`.
+	* The pure primitive: a non-Effect caller (a build script, a Vite plugin,
+	* a language-server tick) can call this directly instead of wrapping
+	* `Effect.runSync(Effect.result(Markdown.parse(text)))`.
+	*
+	* @remarks
+	* {@link Markdown.parse} is defined in terms of this function; the two
+	* never diverge. Reach for the `Effect` variant inside Effect code — it
+	* carries the `Markdown.parse` tracing span — and for this one at
+	* synchronous boundaries. This function carries no span: it is not an
+	* `Effect`.
+	*
+	* Failure is rare by design: every string is a valid markdown document in
+	* both dialects, so the only failures are hardening-guard trips such as
+	* nesting past the 256-container cap. Programmer errors are not converted
+	* — they propagate as thrown defects.
+	*
+	* @example
+	* ```ts
+	* import { Markdown } from "@effected/markdown";
+	* import { Result } from "effect";
+	*
+	* const ok = Markdown.parseResult("# Title\n\nBody *text*.\n");
+	* if (Result.isSuccess(ok)) {
+	*   console.log(ok.success.children.length); // => 2
+	* }
+	* ```
+	*
+	* @param text - The markdown source to parse.
+	* @param options - Optional {@link MarkdownParseOptions}; the dialect
+	*   defaults to `"gfm"`.
+	* @returns A `Result` succeeding with the document {@link Root}, or
+	*   failing with {@link MarkdownParseError}.
+	*/
+	static parseResult(text, options) {
+		return Result.map(parsePassResult(text, options), (pass) => pass.root);
+	}
+	/**
+	* Parse markdown into a {@link Root} tree. Defined in terms of
+	* {@link Markdown.parseResult} — synchronous callers can use that variant
+	* directly.
+	*
+	* @param text - The markdown source to parse.
+	* @param options - Optional {@link MarkdownParseOptions}; the dialect
+	*   defaults to `"gfm"`.
+	* @returns An `Effect` that succeeds with the document {@link Root}, or
+	*   fails with {@link MarkdownParseError}.
+	*/
+	static parse = Effect.fn("Markdown.parse")((text, options) => Effect.fromResult(Markdown.parseResult(text, options)));
+	/**
+	* Serialize a {@link Root} tree to canonical markdown, synchronously, as a
+	* `Result`. The pure primitive twin of {@link Markdown.stringify}, on the
+	* same terms as {@link Markdown.parseResult}.
+	*
+	* @remarks
+	* Canonical serialization: fidelity fields (marker characters, fence
+	* style, heading spelling) win when present; documented canonical
+	* defaults apply when absent. The output re-parses to a render-equivalent
+	* document — the corpus-pinned contract — but is not a byte-level
+	* round-trip of any original source; surgical editing goes through the
+	* offset-splice edit layer instead.
+	*
+	* Failure is rare by design, symmetric with parse: only a hardening-guard
+	* trip on a tree nesting past the depth cap fails, and only synthesized
+	* or decoded trees can nest that far.
+	*
+	* @param root - The document tree to serialize.
+	* @returns A `Result` succeeding with markdown source, or failing with
+	*   {@link MarkdownStringifyError}.
+	*/
+	static stringifyResult(root) {
+		try {
+			return Result.succeed(stringifyTree(root));
+		} catch (caught) {
+			if (isGuardExceeded(caught)) return Result.fail(new MarkdownStringifyError({ diagnostic: MarkdownDiagnostic.make({
+				code: caught.reason,
+				message: caught.message,
+				offset: caught.offset,
+				length: 0,
+				line: 0,
+				character: 0
+			}) }));
+			throw caught;
+		}
+	}
+	/**
+	* Serialize a {@link Root} tree to canonical markdown. Defined in terms of
+	* {@link Markdown.stringifyResult} — synchronous callers can use that
+	* variant directly.
+	*
+	* @param root - The document tree to serialize.
+	* @returns An `Effect` that succeeds with markdown source, or fails with
+	*   {@link MarkdownStringifyError}.
+	*/
+	static stringify = Effect.fn("Markdown.stringify")((root) => Effect.fromResult(Markdown.stringifyResult(root)));
+	/**
+	* A `Schema<Root, string>` decoding markdown source into a {@link Root}
+	* tree and encoding a tree back to canonical markdown via
+	* {@link Markdown.stringifyResult}.
+	*
+	* @remarks
+	* Schema-producing: each call returns a fresh schema whose derivation
+	* caches are not shared across calls. Bind the result to a `const` on hot
+	* paths; the pre-bound {@link Markdown.MarkdownFromString} covers the
+	* common case.
+	*
+	* @param options - Optional {@link MarkdownParseOptions} applied on
+	*   decode.
+	* @returns A `Schema.Codec<Root, string>`.
+	*/
+	static fromString(options) {
+		return Schema.String.pipe(Schema.decodeTo(Root, SchemaTransformation.transformOrFail({
+			decode: (input) => Effect.mapError(Markdown.parse(input, options), (error) => new SchemaIssue.InvalidValue(Option.some(input), { message: error.message })),
+			encode: (value) => Effect.mapError(Markdown.stringify(value), (error) => new SchemaIssue.InvalidValue(Option.some(value), { message: error.message }))
+		})));
+	}
+	/**
+	* The zero-config `Schema<Root, string>` — `Markdown.fromString()`
+	* pre-bound so the common case needs no memoization discipline.
+	*/
+	static MarkdownFromString = Markdown.fromString();
+};
+
+//#endregion
+export { Markdown, MarkdownDialect, MarkdownParseError, MarkdownParseOptions, MarkdownStringifyError, parsePassResult };

package/MarkdownDiagnostic.js

@@ -0,0 +1,85 @@
+import { MARKDOWN_PARSE_ERROR_CODES } from "./internal/carriers.js";
+import { Schema } from "effect";
+
+//#region src/MarkdownDiagnostic.ts
+/**
+* Error codes `Markdown.parse`/`MarkdownDocument.parse` can fail with. P1
+* registers exactly the hardening-guard trip; later phases widen the union
+* as new fatal (as opposed to diagnostic-only) conditions are identified.
+*
+* @public
+*/
+const MarkdownParseErrorCode = Schema.Literals(MARKDOWN_PARSE_ERROR_CODES);
+/**
+* One structured diagnostic: its {@link (MarkdownParseErrorCode:type)}, a
+* human-readable `message`, and its exact position (`offset`/`length`, plus
+* zero-based `line`/`character`).
+*
+* @remarks
+* The five-field positional core (`code`/`offset`/`length`/`line`/`character`)
+* is structurally identical to `@effected/toml`'s `TomlDiagnostic` (and, by
+* the same cross-package contract, `@effected/jsonc`'s parse-error detail
+* shape and `@effected/yaml`'s `YamlDiagnostic`); `message` is this
+* package's additive extra. `line`/`character` here are zero-based to match
+* that contract — a different numbering from the one-based `line`/`column`
+* unist `Point`s carried on `MarkdownNode` positions (`internal/lineIndex.ts`),
+* which is a deliberate, unrelated convention for the AST rather than a
+* mismatch to reconcile.
+*
+* @public
+*/
+var MarkdownDiagnostic = class MarkdownDiagnostic extends Schema.Class("MarkdownDiagnostic")({
+	code: MarkdownParseErrorCode,
+	message: Schema.String,
+	offset: Schema.Number,
+	length: Schema.Number,
+	line: Schema.Number,
+	character: Schema.Number
+}) {
+	/**
+	* Materialize an engine record, deriving zero-based `line`/`character`
+	* from `offset` against the source `text`. Advanced — the parse entry
+	* points call this for you.
+	*/
+	static fromRaw(source, raw) {
+		const { line, character } = lineChar(source, raw.offset);
+		return MarkdownDiagnostic.make({
+			code: raw.code,
+			message: raw.message,
+			offset: raw.offset,
+			length: raw.length,
+			line,
+			character
+		});
+	}
+};
+/**
+* Compute the zero-based line/character position of `offset` within `text`.
+* Recognizes `\n`, `\r` and `\r\n` as line breaks; a CRLF pair counts as a
+* single newline (toml `TomlDiagnostic` precedent — kept independent of
+* `internal/lineIndex.ts`, which answers a different, one-based question
+* for AST positions).
+*/
+function lineChar(text, offset) {
+	let line = 0;
+	let lineStart = 0;
+	const limit = Math.min(offset, text.length);
+	for (let i = 0; i < limit; i++) {
+		const ch = text.charCodeAt(i);
+		if (ch === 10) {
+			line++;
+			lineStart = i + 1;
+		} else if (ch === 13) {
+			if (i + 1 < text.length && text.charCodeAt(i + 1) === 10) i++;
+			line++;
+			lineStart = i + 1;
+		}
+	}
+	return {
+		line,
+		character: offset - lineStart
+	};
+}
+
+//#endregion
+export { MarkdownDiagnostic, MarkdownParseErrorCode };

package/MarkdownDocument.js

@@ -0,0 +1,248 @@
+import { MarkdownRange } from "./MarkdownEdit.js";
+import { Definition, Root } from "./MarkdownNode.js";
+import { normalizeLabelText } from "./internal/references.js";
+import { MarkdownDiagnostic } from "./MarkdownDiagnostic.js";
+import { parsePassResult } from "./Markdown.js";
+import { Effect, Result, Schema } from "effect";
+
+//#region src/MarkdownDocument.ts
+const walkTree = (node, depth, visit) => {
+	if (depth > 256) throw new Error(`NestingDepthExceeded: limit ${256} exceeded while walking the document tree`);
+	visit(node);
+	if ("children" in node) for (const child of node.children) walkTree(child, depth + 1, visit);
+};
+const findInTree = (node, depth, predicate) => {
+	if (depth > 256) throw new Error(`NestingDepthExceeded: limit ${256} exceeded while walking the document tree`);
+	if (predicate(node)) return node;
+	if ("children" in node) for (const child of node.children) {
+		const found = findInTree(child, depth + 1, predicate);
+		if (found !== void 0) return found;
+	}
+};
+/** Normalize a find/findAll selector — a `type` tag or a predicate — to a predicate. */
+const selectorPredicate = (selector) => typeof selector === "string" ? (node) => node.type === selector : selector;
+const phrasingText = (nodes) => {
+	let out = "";
+	for (const node of nodes) switch (node.type) {
+		case "text":
+		case "inlineCode":
+			out += node.value;
+			break;
+		case "break":
+			out += " ";
+			break;
+		case "image":
+		case "imageReference":
+			out += node.alt ?? "";
+			break;
+		case "emphasis":
+		case "strong":
+		case "delete":
+		case "link":
+		case "linkReference":
+			out += phrasingText(node.children);
+			break;
+		default: break;
+	}
+	return out;
+};
+/**
+* A parsed markdown document: the original `source`, the mdast-shaped
+* {@link Root} tree, the non-fatal {@link MarkdownDiagnostic}s the parse
+* produced, and the link-reference `definitions` index.
+*
+* @remarks
+* The document is the lossless unit — `source` is retained so offsets on the
+* tree stay meaningful and so P4's edit/format layer can splice against the
+* exact bytes that were parsed.
+*
+* `definitions` is an index over the {@link Definition} nodes that remain in
+* the tree, keyed by case-folded label with the first definition winning; it
+* is not a place they were moved to. References are emitted unresolved, so
+* resolution happens against this map.
+*
+* `diagnostics` is empty for every input the P1 parser accepts, and that is
+* the current state of the world rather than a missing feature: the plumbing
+* from the engine through to this field is real and exercised, but no P1
+* construct emits a non-fatal diagnostic yet. The producers arrive with the
+* conditions that warrant them — unresolved link references, and
+* present-but-unparseable frontmatter in P3. Read an empty array as "nothing
+* to report", not as "not implemented", and do not code against it staying
+* empty.
+*
+* The navigation accessors (`headings`, `sections`, `links`) are derived
+* getters over the tree — no stored state, no parse-time cost, and they can
+* never disagree with the tree they read.
+*
+* @public
+*/
+var MarkdownDocument = class MarkdownDocument extends Schema.Class("MarkdownDocument")({
+	source: Schema.String,
+	root: Root,
+	diagnostics: Schema.Array(MarkdownDiagnostic),
+	definitions: Schema.ReadonlyMap(Schema.String, Definition)
+}) {
+	/**
+	* The document's frontmatter capture, or `undefined` when there is none.
+	*
+	* @remarks
+	* Derived from the tree rather than stored: a {@link Frontmatter} node can
+	* only ever sit at the head of `root.children` (the capture fires at most
+	* once, at offset 0), so the tree is the single source of truth and the
+	* accessor can never disagree with it. `undefined` covers both a document
+	* with no frontmatter block and one parsed with the capture toggle off.
+	*/
+	get frontmatter() {
+		const head = this.root.children[0];
+		return head !== void 0 && head.type === "frontmatter" ? head : void 0;
+	}
+	/**
+	* Every heading in the document, in document order, wherever it sits —
+	* including headings nested inside blockquotes and list items.
+	*
+	* @remarks
+	* Each {@link DocumentHeading} carries the node, its depth and its
+	* plain-text content. For an outline restricted to section boundaries, use
+	* {@link MarkdownDocument.sections}, which considers root-level headings
+	* only.
+	*/
+	get headings() {
+		const entries = [];
+		for (const child of this.root.children) walkTree(child, 1, (node) => {
+			if (node.type === "heading") entries.push({
+				node,
+				depth: node.depth,
+				text: phrasingText(node.children)
+			});
+		});
+		return entries;
+	}
+	/**
+	* The document's heading-delimited sections, flat and in document order.
+	*
+	* @remarks
+	* Only root-level headings delimit sections — a heading inside a
+	* blockquote or list cannot mark a span of root-level source. Content
+	* before the first heading (the preamble) and the frontmatter block belong
+	* to no section. Each {@link DocumentSection.range} is spliceable by the
+	* edit layer: it runs from the heading's start offset to the next
+	* boundary heading's start, or to the end of the source.
+	*/
+	get sections() {
+		const blocks = this.root.children;
+		const sections = [];
+		for (let index = 0; index < blocks.length; index += 1) {
+			const block = blocks[index];
+			if (block === void 0 || block.type !== "heading") continue;
+			let boundary = this.source.length;
+			let end = blocks.length;
+			for (let next = index + 1; next < blocks.length; next += 1) {
+				const candidate = blocks[next];
+				if (candidate !== void 0 && candidate.type === "heading" && candidate.depth <= block.depth) {
+					boundary = candidate.position.start.offset;
+					end = next;
+					break;
+				}
+			}
+			const start = block.position.start.offset;
+			sections.push({
+				heading: block,
+				depth: block.depth,
+				range: MarkdownRange.make({
+					offset: start,
+					length: boundary - start
+				}),
+				children: blocks.slice(index + 1, end).filter((child) => child.type !== "frontmatter")
+			});
+		}
+		return sections;
+	}
+	/**
+	* Every link-bearing node in the document, in document order: links,
+	* images, definitions, and the reference forms resolved through the
+	* definition index.
+	*
+	* @remarks
+	* See {@link DocumentLink} for the url semantics — the raw `url` string
+	* passes through unmodified, and an unresolvable foreign reference leaves
+	* the field genuinely absent. Autolinks and GFM autolink literals are
+	* {@link Link} nodes, so they appear with no special casing. Footnote
+	* references carry no URL and are not link entries.
+	*/
+	get links() {
+		const entries = [];
+		for (const child of this.root.children) walkTree(child, 1, (node) => {
+			switch (node.type) {
+				case "link":
+				case "image":
+				case "definition":
+					entries.push({
+						node,
+						url: node.url
+					});
+					break;
+				case "linkReference":
+				case "imageReference": {
+					const definition = this.definitions.get(normalizeLabelText(node.identifier));
+					entries.push(definition === void 0 ? { node } : {
+						node,
+						url: definition.url
+					});
+					break;
+				}
+				default: break;
+			}
+		});
+		return entries;
+	}
+	find(selector) {
+		return findInTree(this.root, 0, selectorPredicate(selector));
+	}
+	findAll(selector) {
+		const predicate = selectorPredicate(selector);
+		const matches = [];
+		walkTree(this.root, 0, (node) => {
+			if (predicate(node)) matches.push(node);
+		});
+		return matches;
+	}
+	/**
+	* Parse markdown into a {@link MarkdownDocument}, synchronously, as a
+	* `Result`. The pure primitive; {@link MarkdownDocument.parse} is defined
+	* in terms of it, so the two never diverge.
+	*
+	* @remarks
+	* Carries no span: it is not an `Effect`. Effect callers should reach for
+	* {@link MarkdownDocument.parse}, which carries the
+	* `MarkdownDocument.parse` tracing span.
+	*
+	* @param text - The markdown source to parse.
+	* @param options - Optional {@link MarkdownParseOptions}; the dialect
+	*   defaults to `"gfm"`.
+	* @returns A `Result` succeeding with the document, or failing with
+	*   `MarkdownParseError`.
+	*/
+	static parseResult(text, options) {
+		return Result.map(parsePassResult(text, options), (pass) => MarkdownDocument.make({
+			source: text,
+			root: pass.root,
+			diagnostics: pass.carriers.map((carrier) => MarkdownDiagnostic.fromRaw(text, carrier)),
+			definitions: pass.refmap
+		}));
+	}
+	/**
+	* Parse markdown into a {@link MarkdownDocument}. Defined in terms of
+	* {@link MarkdownDocument.parseResult} — synchronous callers can use that
+	* variant directly.
+	*
+	* @param text - The markdown source to parse.
+	* @param options - Optional {@link MarkdownParseOptions}; the dialect
+	*   defaults to `"gfm"`.
+	* @returns An `Effect` that succeeds with the document, or fails with
+	*   `MarkdownParseError`.
+	*/
+	static parse = Effect.fn("MarkdownDocument.parse")((text, options) => Effect.fromResult(MarkdownDocument.parseResult(text, options)));
+};
+
+//#endregion
+export { MarkdownDocument };

package/MarkdownEdit.js

@@ -0,0 +1,52 @@
+import { Schema } from "effect";
+
+//#region src/MarkdownEdit.ts
+/**
+* A range within a markdown document, expressed as a zero-based character
+* `offset` and a `length` in UTF-16 code units. Pass to `MarkdownFormat.format`
+* to restrict formatting to a region.
+*
+* @public
+*/
+var MarkdownRange = class extends Schema.Class("MarkdownRange")({
+	offset: Schema.Number,
+	length: Schema.Number
+}) {};
+/**
+* A non-mutating text edit: replace the span `[offset, offset + length)` with
+* `content`. Set `length` to `0` to insert, `content` to `""` to delete.
+*
+* @remarks
+* Structurally identical to `@effected/jsonc`'s, `@effected/yaml`'s and
+* `@effected/toml`'s edit shapes (same field names, types and semantics) per
+* the cross-package parity convention, so consumer code can be written once
+* over "a document codec's Edit/Range/Path".
+*
+* @public
+*/
+var MarkdownEdit = class extends Schema.Class("MarkdownEdit")({
+	offset: Schema.Number,
+	length: Schema.Number,
+	content: Schema.String
+}) {
+	/**
+	* Apply `edits` to `text`, producing a new string. Edits are applied in
+	* reverse-offset order so earlier offsets stay valid; the input `edits`
+	* array is not mutated. Overlapping edits are a programmer error and throw
+	* as a defect — `MarkdownFormat` never produces them.
+	*/
+	static applyAll(text, edits) {
+		const sorted = [...edits].sort((a, b) => b.offset - a.offset);
+		for (let i = 0; i + 1 < sorted.length; i++) {
+			const upper = sorted[i];
+			const lower = sorted[i + 1];
+			if (lower.offset + lower.length > upper.offset) throw new Error(`MarkdownEdit.applyAll received overlapping edits at offsets ${lower.offset} and ${upper.offset} — overlapping edits are a programmer error`);
+		}
+		let result = text;
+		for (const edit of sorted) result = result.slice(0, edit.offset) + edit.content + result.slice(edit.offset + edit.length);
+		return result;
+	}
+};
+
+//#endregion
+export { MarkdownEdit, MarkdownRange };