@effected/markdown 0.2.0

package/MarkdownFormat.js

@@ -0,0 +1,380 @@
+import { MarkdownEdit } from "./MarkdownEdit.js";
+import { BulletChar, EmphasisChar, FenceChar, HeadingStyle, Paragraph, Root, Text, ThematicBreakChar } from "./MarkdownNode.js";
+import { Markdown, MarkdownDialect, MarkdownParseOptions } from "./Markdown.js";
+import { Effect, Result, Schema } from "effect";
+
+//#region src/MarkdownFormat.ts
+/**
+* Options controlling formatting: which concrete-syntax markers to normalize,
+* plus the parse knobs (`dialect`, `frontmatter`) the formatter parses the
+* source with (same defaults as `Markdown.parse`). Every marker option is
+* optional and independent; an absent option normalizes nothing.
+*
+* Day-one scope is marker normalization only — heading style, bullet
+* character, emphasis/strong marker, fence character, thematic-break
+* character. Content is never rewritten, rewrapped or reflowed.
+*
+* @public
+*/
+var MarkdownFormattingOptions = class extends Schema.Class("MarkdownFormattingOptions")({
+	dialect: Schema.optionalKey(MarkdownDialect),
+	frontmatter: Schema.optionalKey(Schema.Boolean),
+	headingStyle: Schema.optionalKey(HeadingStyle),
+	bulletChar: Schema.optionalKey(BulletChar),
+	emphasisChar: Schema.optionalKey(EmphasisChar),
+	fenceChar: Schema.optionalKey(FenceChar),
+	thematicBreakChar: Schema.optionalKey(ThematicBreakChar)
+}) {};
+/**
+* Error codes `MarkdownFormat.modify` can fail with.
+*
+* @public
+*/
+const MarkdownModificationErrorCode = Schema.Literals([
+	"NodeNotInDocument",
+	"UnsupportedTarget",
+	"FragmentCategoryMismatch",
+	"FragmentUnrenderable"
+]);
+/**
+* Raised when `MarkdownFormat.modify` cannot perform the requested
+* replacement: the target node is not in the document (`NodeNotInDocument`),
+* the target kind or splice context is outside the day-one scope
+* (`UnsupportedTarget`), the fragment's content category does not fit the
+* target's slot (`FragmentCategoryMismatch`), or the fragment trips the
+* stringifier's hardening guard (`FragmentUnrenderable`). Carries the typed
+* `code` plus the target's `offset`/`length` where known — never a collapsed
+* reason string alone.
+*
+* @public
+*/
+var MarkdownModificationError = class extends Schema.TaggedErrorClass()("MarkdownModificationError", {
+	code: MarkdownModificationErrorCode,
+	detail: Schema.String,
+	offset: Schema.Number,
+	length: Schema.Number
+}) {
+	get message() {
+		return `Markdown modification failed: ${this.code} ${this.detail}`;
+	}
+};
+const childrenOf = (node) => node.children ?? [];
+/** Walk the tree, invoking `visit` with each node, its parent and its siblings. */
+const walk = (node, parent, siblings, index, visit) => {
+	visit(node, parent, siblings, index);
+	const children = childrenOf(node);
+	for (let i = 0; i < children.length; i++) walk(children[i], node, children, i, visit);
+};
+const spanOf = (node) => ({
+	start: node.position.start.offset,
+	end: node.position.end.offset
+});
+const ALPHANUMERIC = /[\p{L}\p{N}]/u;
+/** The start offset of the line containing `offset`. */
+const lineStartOf = (source, offset) => {
+	let i = offset;
+	while (i > 0 && source.charCodeAt(i - 1) !== 10) i--;
+	return i;
+};
+/** True when the line before the one containing `offset` is blank or absent. */
+const previousLineBlank = (source, offset) => {
+	const lineStart = lineStartOf(source, offset);
+	if (lineStart === 0) return true;
+	let i = lineStart - 1;
+	if (i > 0 && source.charCodeAt(i - 1) === 13) i--;
+	const prevStart = lineStartOf(source, i);
+	for (let j = prevStart; j < i; j++) {
+		const code = source.charCodeAt(j);
+		if (code !== 32 && code !== 9) return false;
+	}
+	return true;
+};
+/** Content that cannot stand as a setext heading's text line. */
+const SETEXT_CONTENT_HAZARD = /^(?:[-+*>#=]|\d{1,9}[.)](?:\s|$)|`{3}|~{3}|\s)/;
+/** The longest run of `char` anywhere in `value`. */
+const longestRun = (value, char) => {
+	let longest = 0;
+	let current = 0;
+	for (const ch of value) {
+		current = ch === char ? current + 1 : 0;
+		if (current > longest) longest = current;
+	}
+	return longest;
+};
+const isUnorderedList = (node) => node.type === "list" && node.ordered !== true;
+/** True when only blank text separates the two spans. */
+const adjacentSpans = (source, endOfFirst, startOfSecond) => {
+	for (let i = endOfFirst; i < startOfSecond; i++) {
+		const code = source.charCodeAt(i);
+		if (code !== 32 && code !== 9 && code !== 10 && code !== 13) return false;
+	}
+	return true;
+};
+/** Accumulates format edits; drops no-op splices to keep format idempotent. */
+var FormatEmitter = class {
+	source;
+	edits = [];
+	constructor(source) {
+		this.source = source;
+	}
+	push(node, offset, length, content) {
+		if (this.source.slice(offset, offset + length) !== content) {
+			const { start, end } = spanOf(node);
+			this.edits.push({
+				offset,
+				length,
+				content,
+				nodeStart: start,
+				nodeEnd: end
+			});
+		}
+	}
+};
+const formatThematicBreak = (source, emit, node, target) => {
+	if ((node.markerChar ?? "*") === target) return;
+	const { start, end } = spanOf(node);
+	if (target === "-" && !previousLineBlank(source, start)) return;
+	emit.push(node, start, end - start, target.repeat(3));
+};
+const formatHeading = (source, emit, node, target) => {
+	if ((node.headingStyle ?? "atx") === target || node.children.length === 0) return;
+	const { start, end } = spanOf(node);
+	const contentStart = node.children[0].position.start.offset;
+	const contentEnd = node.children[node.children.length - 1].position.end.offset;
+	const content = source.slice(contentStart, contentEnd);
+	if (content.includes("\n") || content.includes("\r")) return;
+	if (target === "atx") {
+		emit.push(node, start, end - start, `${"#".repeat(node.depth)} ${content}`);
+		return;
+	}
+	if (node.depth > 2 || content.length === 0 || SETEXT_CONTENT_HAZARD.test(content)) return;
+	if (start !== 0 && source.charCodeAt(start - 1) !== 10) return;
+	const underline = (node.depth === 1 ? "=" : "-").repeat(Math.max(3, content.length));
+	emit.push(node, start, end - start, `${content}\n${underline}`);
+};
+const formatList = (source, emit, node, siblings, index, target) => {
+	if (!isUnorderedList(node) || (node.bulletChar ?? "-") === target) return;
+	const previous = index > 0 ? siblings[index - 1] : void 0;
+	const next = index + 1 < siblings.length ? siblings[index + 1] : void 0;
+	const { start, end } = spanOf(node);
+	if (previous !== void 0 && isUnorderedList(previous) && adjacentSpans(source, spanOf(previous).end, start)) return;
+	if (next !== void 0 && isUnorderedList(next) && adjacentSpans(source, end, spanOf(next).start)) return;
+	for (const item of node.children) emit.push(node, item.position.start.offset, 1, target);
+};
+const isEmphasisLike = (node) => node.type === "emphasis" || node.type === "strong";
+const formatEmphasis = (source, emit, node, siblings, index, target) => {
+	if ((node.markerChar ?? "*") === target) return;
+	const markerLength = node.type === "strong" ? 2 : 1;
+	const { start, end } = spanOf(node);
+	if (target === "_" && (start > 0 && ALPHANUMERIC.test(source[start - 1]) || end < source.length && ALPHANUMERIC.test(source[end]))) return;
+	for (const child of childrenOf(node)) {
+		if (!isEmphasisLike(child)) continue;
+		const childSpan = spanOf(child);
+		if (childSpan.start === start + markerLength || childSpan.end === end - markerLength) return;
+	}
+	const previous = index > 0 ? siblings[index - 1] : void 0;
+	const next = index + 1 < siblings.length ? siblings[index + 1] : void 0;
+	if (previous !== void 0 && isEmphasisLike(previous) && spanOf(previous).end === start) return;
+	if (next !== void 0 && isEmphasisLike(next) && spanOf(next).start === end) return;
+	emit.push(node, start, markerLength, target.repeat(markerLength));
+	emit.push(node, end - markerLength, markerLength, target.repeat(markerLength));
+};
+const formatFence = (source, emit, node, target) => {
+	const fidelity = node.fenceChar;
+	if (fidelity === void 0 || fidelity === target) return;
+	if (target === "`" && `${node.lang ?? ""}${node.meta ?? ""}`.includes("`")) return;
+	const { start, end } = spanOf(node);
+	let openLength = 0;
+	while (start + openLength < end && source[start + openLength] === fidelity) openLength++;
+	if (openLength === 0) return;
+	const newLength = Math.max(3, openLength, longestRun(node.value, target) + 1);
+	emit.push(node, start, openLength, target.repeat(newLength));
+	let closeLength = 0;
+	while (end - closeLength > start + openLength && source[end - closeLength - 1] === fidelity) closeLength++;
+	if (closeLength >= 3) emit.push(node, end - closeLength, closeLength, target.repeat(newLength));
+};
+const FLOW_TYPES = /* @__PURE__ */ new Set([
+	"blockquote",
+	"code",
+	"definition",
+	"footnoteDefinition",
+	"heading",
+	"html",
+	"list",
+	"paragraph",
+	"table",
+	"thematicBreak"
+]);
+const PHRASING_TYPES = /* @__PURE__ */ new Set([
+	"break",
+	"delete",
+	"emphasis",
+	"footnoteReference",
+	"html",
+	"image",
+	"imageReference",
+	"inlineCode",
+	"link",
+	"linkReference",
+	"strong",
+	"text"
+]);
+/** Parent types whose child slot holds flow content. */
+const FLOW_PARENTS = /* @__PURE__ */ new Set([
+	"root",
+	"blockquote",
+	"listItem",
+	"footnoteDefinition"
+]);
+/** Parent types whose child slot holds phrasing content. */
+const PHRASING_PARENTS = /* @__PURE__ */ new Set([
+	"paragraph",
+	"heading",
+	"emphasis",
+	"strong",
+	"delete",
+	"link",
+	"linkReference",
+	"tableCell"
+]);
+/** Ancestor types whose continuation lines carry a prefix (or forbid newlines outright). */
+const NO_MULTILINE_ANCESTORS = /* @__PURE__ */ new Set([
+	"blockquote",
+	"list",
+	"listItem",
+	"footnoteDefinition",
+	"table",
+	"tableRow",
+	"tableCell",
+	"heading"
+]);
+/** Find `target` by identity; returns its ancestor chain (nearest first) or undefined. */
+const findAncestry = (root, target) => {
+	const search = (node, trail) => {
+		if (node === target) return trail;
+		for (const child of childrenOf(node)) {
+			const found = search(child, [node, ...trail]);
+			if (found !== void 0) return found;
+		}
+	};
+	return search(root, []);
+};
+/**
+* Formatting and modification statics. Not instantiable.
+*
+* @remarks
+* `format`/`formatToString` are pure and total: input that trips a parse
+* hardening guard yields no edits rather than corrupting the document, and
+* every emitted edit is guarded against the re-parse hazards listed in the
+* module documentation — a hazardous conversion is skipped, never attempted.
+* `modify`/`modifyToString` carry a real error channel
+* ({@link MarkdownModificationError}) and render every replacement through
+* the canonical stringifier, so a modified document re-parses cleanly by
+* construction.
+*
+* @public
+*/
+var MarkdownFormat = class MarkdownFormat {
+	constructor() {}
+	/**
+	* Compute marker-normalization edits per the requested
+	* {@link MarkdownFormattingOptions}: heading style, bullet character,
+	* emphasis/strong marker, fence character and thematic-break character,
+	* each only where the node's concrete syntax differs from the target and
+	* the rewrite is provably safe. Content is never touched. `range`
+	* restricts edits to the nodes intersecting it (the owning-node
+	* intersection posture, matching toml). Non-mutating — apply with
+	* `MarkdownEdit.applyAll` (or use {@link MarkdownFormat.formatToString}).
+	*/
+	static format(text, range, options) {
+		const parsed = Markdown.parseResult(text, MarkdownParseOptions.make({
+			...options?.dialect !== void 0 ? { dialect: options.dialect } : {},
+			...options?.frontmatter !== void 0 ? { frontmatter: options.frontmatter } : {}
+		}));
+		if (Result.isFailure(parsed)) return [];
+		const emit = new FormatEmitter(text);
+		walk(parsed.success, void 0, [], 0, (node, _parent, siblings, index) => {
+			if (options?.thematicBreakChar !== void 0 && node.type === "thematicBreak") formatThematicBreak(text, emit, node, options.thematicBreakChar);
+			if (options?.headingStyle !== void 0 && node.type === "heading") formatHeading(text, emit, node, options.headingStyle);
+			if (options?.bulletChar !== void 0 && node.type === "list") formatList(text, emit, node, siblings, index, options.bulletChar);
+			if (options?.emphasisChar !== void 0 && isEmphasisLike(node)) formatEmphasis(text, emit, node, siblings, index, options.emphasisChar);
+			if (options?.fenceChar !== void 0 && node.type === "code") formatFence(text, emit, node, options.fenceChar);
+		});
+		return (range === void 0 ? emit.edits : emit.edits.filter((edit) => Math.max(edit.nodeStart, range.offset) <= Math.min(edit.nodeEnd, range.offset + range.length))).map((edit) => MarkdownEdit.make({
+			offset: edit.offset,
+			length: edit.length,
+			content: edit.content
+		}));
+	}
+	/**
+	* Format `text` and apply the resulting edits in one step
+	* (`MarkdownEdit.applyAll ∘ format`). Pure and total.
+	*/
+	static formatToString(text, range, options) {
+		return MarkdownEdit.applyAll(text, MarkdownFormat.format(text, range, options));
+	}
+	/**
+	* Compute the edit that replaces `target` — a node from `document`'s own
+	* tree, matched by identity — with `replacement`: a plain string (treated
+	* as literal text and escaped; block-wrapped when the target is a flow
+	* node) or a node fragment whose content category must fit the target's
+	* slot (flow for flow targets, phrasing for phrasing targets and table
+	* cells). Every replacement renders through the canonical stringifier, so
+	* the modified document re-parses cleanly by construction. Day-one scope:
+	* list items, table rows, frontmatter and the root refuse with
+	* `UnsupportedTarget`, as does a multi-line replacement whose target sits
+	* inside a container (a blockquote, list, table or heading) whose
+	* continuation lines the splice cannot prefix.
+	*/
+	static modify = Effect.fn("MarkdownFormat.modify")(function* (document, target, replacement) {
+		const { start, end } = spanOf(target);
+		const fail = (code, detail) => new MarkdownModificationError({
+			code,
+			detail,
+			offset: start,
+			length: end - start
+		});
+		const ancestry = findAncestry(document.root, target);
+		if (ancestry === void 0) return yield* fail("NodeNotInDocument", "the target node is not part of the document's tree");
+		const parent = ancestry[0];
+		if (parent === void 0 || target.type === "frontmatter") return yield* fail("UnsupportedTarget", `a ${target.type} node cannot be replaced`);
+		let slot;
+		if (target.type === "tableCell" && parent.type === "tableRow") slot = "cell";
+		else if (FLOW_PARENTS.has(parent.type)) slot = "flow";
+		else if (PHRASING_PARENTS.has(parent.type)) slot = "phrasing";
+		else return yield* fail("UnsupportedTarget", `a ${target.type} node inside a ${parent.type} cannot be replaced`);
+		let renderRoot;
+		if (typeof replacement === "string") {
+			const textNode = Text.make({ value: replacement });
+			const paragraph = Paragraph.make({ children: [textNode] });
+			renderRoot = Root.make({ children: [paragraph] });
+		} else if (slot === "flow") {
+			if (!FLOW_TYPES.has(replacement.type)) return yield* fail("FragmentCategoryMismatch", `a ${replacement.type} fragment does not fit a flow slot — pass flow content or a plain string`);
+			renderRoot = Root.make({ children: [replacement] });
+		} else {
+			if (!PHRASING_TYPES.has(replacement.type)) return yield* fail("FragmentCategoryMismatch", `a ${replacement.type} fragment does not fit a phrasing slot — pass phrasing content or a plain string`);
+			const paragraph = Paragraph.make({ children: [replacement] });
+			renderRoot = Root.make({ children: [paragraph] });
+		}
+		const rendered = Markdown.stringifyResult(renderRoot);
+		if (Result.isFailure(rendered)) return yield* fail("FragmentUnrenderable", rendered.failure.message);
+		const content = rendered.success.replace(/\n+$/, "");
+		if (content.includes("\n") && ancestry.some((ancestor) => NO_MULTILINE_ANCESTORS.has(ancestor.type))) return yield* fail("UnsupportedTarget", "a multi-line replacement cannot be spliced inside a container whose continuation lines carry a prefix");
+		return [MarkdownEdit.make({
+			offset: start,
+			length: end - start,
+			content
+		})];
+	});
+	/**
+	* Modify `document` and apply the resulting edit in one step
+	* (`MarkdownEdit.applyAll ∘ modify`).
+	*/
+	static modifyToString = Effect.fn("MarkdownFormat.modifyToString")(function* (document, target, replacement) {
+		const edits = yield* MarkdownFormat.modify(document, target, replacement);
+		return MarkdownEdit.applyAll(document.source, edits);
+	});
+};
+
+//#endregion
+export { MarkdownFormat, MarkdownFormattingOptions, MarkdownModificationError, MarkdownModificationErrorCode };