@effected/markdown 0.2.0

package/internal/stringify.js

@@ -0,0 +1,519 @@
+import { GuardExceeded } from "./carriers.js";
+
+//#region src/internal/stringify.ts
+const FLOW_CONTEXT = {
+	singleLine: false,
+	inTable: false,
+	inHeading: false
+};
+const HEADING_CONTEXT = {
+	singleLine: true,
+	inTable: false,
+	inHeading: true
+};
+const CELL_CONTEXT = {
+	singleLine: true,
+	inTable: true,
+	inHeading: false
+};
+/** Characters escaped wherever they appear in inline text. */
+const ALWAYS_ESCAPE = /* @__PURE__ */ new Set([
+	"\\",
+	"`",
+	"*",
+	"_",
+	"[",
+	"]",
+	"<",
+	">",
+	"&",
+	"~",
+	"|"
+]);
+/** Line-start characters that could open a block construct. */
+const LINE_START_ESCAPE = /* @__PURE__ */ new Set([
+	"#",
+	">",
+	"+",
+	"-",
+	"=",
+	"~",
+	"`"
+]);
+const SCHEME_WORDS = /* @__PURE__ */ new Set([
+	"http",
+	"https",
+	"ftp",
+	"mailto",
+	"xmpp"
+]);
+const ORDERED_MARKER = /^\d{1,9}[.)]/;
+const guard = (state, node) => {
+	state.depth += 1;
+	if (state.depth > 256) throw new GuardExceeded("NestingDepthExceeded", 256, state.depth, node.position.start.offset);
+};
+const unguard = (state) => {
+	state.depth -= 1;
+};
+/** Whether `value[index]` ends a `www` run preceded by a word boundary. */
+const isWwwDot = (value, index) => {
+	if (value.slice(Math.max(0, index - 3), index).toLowerCase() !== "www") return false;
+	if (index - 3 <= 0) return true;
+	const before = value[index - 4];
+	return before === void 0 || !/[\p{L}\p{N}]/u.test(before);
+};
+/** Whether the run of letters ending at `value[index]` is a scheme word. */
+const isSchemeColon = (value, index) => {
+	let start = index;
+	while (start > 0 && /[a-zA-Z]/.test(value[start - 1])) start -= 1;
+	return SCHEME_WORDS.has(value.slice(start, index).toLowerCase());
+};
+/**
+* Escape one text value into `out`, tracking line starts. Returns whether the
+* emission ended at a line start.
+*/
+const escapeText = (value, context, atLineStart) => {
+	let out = "";
+	let lineStart = atLineStart;
+	for (let index = 0; index < value.length; index += 1) {
+		const char = value[index];
+		if (char === "\n") {
+			const adjacent = value[index - 1] === "\n" || value[index + 1] === "\n";
+			const atBoundary = index === 0 || index === value.length - 1;
+			if (context.singleLine) {
+				out += " ";
+				lineStart = false;
+			} else if (adjacent || atBoundary) {
+				out += "&#10;";
+				lineStart = false;
+			} else {
+				out += "\n";
+				lineStart = true;
+			}
+			continue;
+		}
+		if (lineStart) {
+			if (char === "	") {
+				out += "&#9;";
+				lineStart = false;
+				continue;
+			}
+			if (char === " ") {
+				out += "&#32;";
+				lineStart = false;
+				continue;
+			}
+			const lineEnd = value.indexOf("\n", index);
+			const restOfLine = value.slice(index, lineEnd === -1 ? void 0 : lineEnd);
+			const ordered = ORDERED_MARKER.exec(restOfLine);
+			if (ordered !== null) {
+				const digits = ordered[0].slice(0, -1);
+				const delimiter = ordered[0].slice(-1);
+				out += `${digits}\\${delimiter}`;
+				index += ordered[0].length - 1;
+				lineStart = false;
+				continue;
+			}
+			if (LINE_START_ESCAPE.has(char)) {
+				out += `\\${char}`;
+				lineStart = false;
+				continue;
+			}
+		}
+		lineStart = false;
+		if (ALWAYS_ESCAPE.has(char)) {
+			out += `\\${char}`;
+			continue;
+		}
+		if (context.inHeading && char === "#") {
+			out += "\\#";
+			continue;
+		}
+		if (char === "." && isWwwDot(value, index)) {
+			out += "\\.";
+			continue;
+		}
+		if (char === ":" && isSchemeColon(value, index)) {
+			out += "\\:";
+			continue;
+		}
+		out += char;
+	}
+	return {
+		text: out,
+		atLineStart: lineStart
+	};
+};
+/** Pick the effective emphasis marker, flipping away from a forbidden char. */
+const emphasisMarker = (fidelity, forbidden) => {
+	const chosen = fidelity ?? "*";
+	return chosen === forbidden ? chosen === "*" ? "_" : "*" : chosen;
+};
+/**
+* Emit a reference label for its bracket. Labels (and identifiers) in this
+* tree are SOURCE-FORM — the parser keeps character escapes unparsed, per
+* the mdast identifier contract — so the label already carries any escapes
+* its content needs and re-emitting it verbatim reproduces the original
+* bracket exactly. The only intervention is protecting a synthesized label's
+* UNESCAPED square brackets, which would otherwise break the bracket
+* structure. Definitions and references run through this same function, so
+* identifiers agree on both ends and resolution holds.
+*/
+const escapeLabel = (label) => label.replace(/(?<!\\)([[\]])/g, "\\$1");
+/** Whether a destination character forces the pointy-bracket form. */
+const forcesPointy = (char) => {
+	return char.codePointAt(0) <= 32 || char === "<" || char === ">" || char === "[" || char === "]" || char === "\\";
+};
+/** Wrap a link/image destination, pointy-bracketed when it needs it. */
+const destination = (url) => {
+	if (url === "" || Array.from(url).some(forcesPointy) || !balancedParens(url)) return `<${url.replace(/[<>\\]/g, (char) => `\\${char}`)}>`;
+	return url;
+};
+const balancedParens = (url) => {
+	let open = 0;
+	for (const char of url) {
+		if (char === "(") open += 1;
+		if (char === ")") {
+			open -= 1;
+			if (open < 0) return false;
+		}
+	}
+	return open === 0;
+};
+const titleSuffix = (title) => title === void 0 ? "" : ` "${title.replace(/[\\"]/g, (char) => `\\${char}`)}"`;
+/** Serialize an inline-code span with a fence run longer than any interior run. */
+const inlineCode = (value) => {
+	let longest = 0;
+	for (const run of value.match(/`+/g) ?? []) longest = Math.max(longest, run.length);
+	const fence = "`".repeat(Math.max(1, longest + 1));
+	return `${fence}${!(value !== "" && value.trim() === "") && (value.startsWith("`") || value.endsWith("`") || value.startsWith(" ") || value.endsWith(" ")) ? ` ${value} ` : value}${fence}`;
+};
+const flipMarker = (marker) => marker === "*" ? "_" : "*";
+/** The edge-marker choice for a nested emphasis-family child. */
+const nestedMarker = (child, fidelity, guard) => {
+	if (guard.parent === "emphasis") return child === "strong" ? guard.marker : flipMarker(guard.marker);
+	return child === "emphasis" ? flipMarker(guard.marker) : fidelity ?? guard.marker;
+};
+/**
+* Serialize a run of phrasing children. `junctionGuard` carries the marker
+* the PARENT emits at this run's edges, so a first or last emphasis-family
+* child flips away from it; mid-run children only flip away from an actual
+* adjacent marker char.
+*/
+const serializeInlines = (children, context, state, startsLine, junctionGuard) => {
+	let out = "";
+	let atLineStart = startsLine;
+	let index = 0;
+	for (const child of children) {
+		guard(state, child);
+		const lastChar = out === "" ? void 0 : out[out.length - 1];
+		const atEdge = out === "" || index === children.length - 1;
+		const adjacentMarker = lastChar === "*" || lastChar === "_" ? lastChar : void 0;
+		const bangGuard = () => {
+			if (out.endsWith("!") && !out.endsWith("\\!")) out = `${out.slice(0, -1)}\\!`;
+		};
+		switch (child.type) {
+			case "text": {
+				const escaped = escapeText(child.value, context, atLineStart);
+				out += escaped.text;
+				atLineStart = escaped.atLineStart;
+				break;
+			}
+			case "inlineCode":
+				out += inlineCode(child.value);
+				atLineStart = false;
+				break;
+			case "html":
+				out += child.value;
+				atLineStart = false;
+				break;
+			case "break":
+				if (context.singleLine) {
+					out += " ";
+					atLineStart = false;
+				} else {
+					out += child.breakStyle === "spaces" ? "  \n" : "\\\n";
+					atLineStart = true;
+				}
+				break;
+			case "emphasis":
+			case "strong": {
+				const kind = child.type;
+				let marker;
+				if (atEdge && junctionGuard !== void 0) marker = nestedMarker(kind, child.markerChar, junctionGuard);
+				else marker = emphasisMarker(child.markerChar, adjacentMarker);
+				if (marker === "_" && lastChar !== void 0 && /[\p{L}\p{N}]/u.test(lastChar)) marker = "*";
+				const run = kind === "strong" ? marker.repeat(2) : marker;
+				const inner = serializeInlines(child.children, context, state, false, {
+					parent: kind,
+					marker
+				});
+				out += `${run}${inner}${run}`;
+				atLineStart = false;
+				break;
+			}
+			case "delete":
+				out += `~~${serializeInlines(child.children, context, state, false)}~~`;
+				atLineStart = false;
+				break;
+			case "link":
+				bangGuard();
+				out += `[${serializeInlines(child.children, context, state, false)}](${destination(child.url)}${titleSuffix(child.title)})`;
+				atLineStart = false;
+				break;
+			case "image": {
+				const alt = (child.alt ?? "").replace(/[\\[\]]/g, (char) => `\\${char}`);
+				out += `![${alt}](${destination(child.url)}${titleSuffix(child.title)})`;
+				atLineStart = false;
+				break;
+			}
+			case "linkReference": {
+				bangGuard();
+				const label = escapeLabel(child.label ?? child.identifier);
+				if (child.referenceType === "full") {
+					const content = serializeInlines(child.children, context, state, false);
+					out += `[${content}][${label}]`;
+				} else if (child.referenceType === "collapsed") out += `[${label}][]`;
+				else out += `[${label}]`;
+				atLineStart = false;
+				break;
+			}
+			case "imageReference": {
+				const label = escapeLabel(child.label ?? child.identifier);
+				if (child.referenceType === "full") {
+					const alt = (child.alt ?? "").replace(/[\\[\]]/g, (char) => `\\${char}`);
+					out += `![${alt}][${label}]`;
+				} else if (child.referenceType === "collapsed") out += `![${label}][]`;
+				else out += `![${label}]`;
+				atLineStart = false;
+				break;
+			}
+			case "footnoteReference":
+				out += `[^${escapeLabel(child.label ?? child.identifier)}]`;
+				atLineStart = false;
+				break;
+		}
+		index += 1;
+		unguard(state);
+	}
+	return out;
+};
+/** Prefix every line of `content`; blank lines take the trimmed prefix. */
+const prefixLines = (content, prefix, blankPrefix) => content.split("\n").map((line) => line === "" ? blankPrefix : `${prefix}${line}`).join("\n");
+/** First line gets `marker`, continuation lines get spaces of its width. */
+const hangingIndent = (content, marker) => {
+	const lines = content.split("\n");
+	const indent = " ".repeat(marker.length);
+	return lines.map((line, index) => {
+		if (index === 0) return `${marker}${line}`;
+		return line === "" ? "" : `${indent}${line}`;
+	}).join("\n");
+};
+const serializeCode = (node, forceFence) => {
+	const value = node.value.endsWith("\n") ? node.value.slice(0, -1) : node.value;
+	const lines = value === "" ? [] : value.split("\n");
+	if (!forceFence && node.fenceChar === void 0 && node.lang === void 0 && node.meta === void 0 && lines.length > 0 && lines[0] !== "" && lines[lines.length - 1] !== "") return lines.map((line) => line === "" ? "" : `    ${line}`).join("\n");
+	const char = node.fenceChar ?? "`";
+	let longest = 0;
+	const runs = value.match(char === "`" ? /`+/g : /~+/g) ?? [];
+	for (const run of runs) longest = Math.max(longest, run.length);
+	const length = Math.max(3, node.fenceLength ?? 0, longest + 1);
+	const fence = char.repeat(length);
+	return `${fence}${`${node.lang ?? ""}${node.meta !== void 0 ? ` ${node.meta}` : ""}`}\n${value === "" ? "" : `${value}\n`}${fence}`;
+};
+const setextUnderline = (heading, content) => {
+	const lastLine = content.split("\n").at(-1) ?? "";
+	return (heading.depth === 1 ? "=" : "-").repeat(Math.max(1, lastLine.length));
+};
+const serializeHeading = (heading, state) => {
+	const content = serializeInlines(heading.children, HEADING_CONTEXT, state, false);
+	if (heading.headingStyle === "setext" && heading.depth <= 2 && content !== "") return `${content}\n${setextUnderline(heading, content)}`;
+	const hashes = "#".repeat(heading.depth);
+	return content === "" ? hashes : `${hashes} ${content}`;
+};
+const serializeDefinition = (node) => `[${escapeLabel(node.label ?? node.identifier)}]: ${destination(node.url)}${titleSuffix(node.title)}`;
+const serializeFootnoteDefinition = (node, state) => {
+	const lines = serializeBlocks(node.children, state).split("\n");
+	const marker = `[^${escapeLabel(node.label ?? node.identifier)}]:`;
+	if (node.children[0]?.type === "code") return [marker, ...lines.map((line) => line === "" ? "" : `    ${line}`)].join("\n");
+	return lines.map((line, index) => {
+		if (index === 0) return `${marker} ${line}`;
+		return line === "" ? "" : `    ${line}`;
+	}).join("\n");
+};
+const alignCell = (align) => {
+	switch (align) {
+		case "left": return ":--";
+		case "right": return "--:";
+		case "center": return ":-:";
+		default: return "---";
+	}
+};
+const serializeTable = (table, state) => {
+	const columnCount = Math.max(1, ...table.children.map((row) => row.children.length));
+	const rows = table.children.map((row) => {
+		guard(state, row);
+		const cells = row.children.map((cell) => {
+			guard(state, cell);
+			const content = serializeInlines(cell.children, CELL_CONTEXT, state, false).replace(/(?<!\\)\|/g, "\\|");
+			unguard(state);
+			return content;
+		});
+		unguard(state);
+		while (cells.length < columnCount) cells.push("");
+		return `| ${cells.join(" | ")} |`;
+	});
+	const alignRow = `| ${Array.from({ length: columnCount }, (_, column) => alignCell(table.align?.[column])).join(" | ")} |`;
+	const [header, ...body] = rows;
+	return [
+		header ?? `| ${Array.from({ length: columnCount }, () => "").join(" | ")} |`,
+		alignRow,
+		...body
+	].join("\n");
+};
+/** The marker actually used by a list, for adjacency comparison. */
+const effectiveListMarker = (list, flipped) => {
+	if (list.ordered === true) {
+		const delimiter = list.delimiter ?? ".";
+		return flipped ? delimiter === "." ? ")" : "." : delimiter;
+	}
+	const bullet = list.bulletChar ?? "-";
+	return flipped ? bullet === "-" ? "*" : "-" : bullet;
+};
+const serializeListItem = (item, marker, state, tight) => {
+	guard(state, item);
+	const inner = serializeBlocks(item.children, state, tight);
+	unguard(state);
+	const content = `${item.checked === void 0 ? "" : item.checked ? "[x] " : "[ ] "}${inner}`;
+	if (content === "") return marker.trimEnd();
+	return hangingIndent(content, marker);
+};
+const serializeList = (list, state, flipped) => {
+	const tight = !(list.spread ?? false);
+	return list.children.map((item, index) => {
+		const marker = list.ordered === true ? `${(list.start ?? 1) + index}${effectiveListMarker(list, flipped)} ` : `${effectiveListMarker(list, flipped)} `;
+		return serializeListItem(item, marker, state, tight);
+	}).join(tight ? "\n" : "\n\n");
+};
+/** Whether `next` interrupts a paragraph without a blank line before it. */
+const interruptsParagraph = (next) => {
+	switch (next.type) {
+		case "list": return next.ordered !== true || (next.start ?? 1) === 1;
+		case "blockquote":
+		case "thematicBreak": return true;
+		case "heading": return next.headingStyle !== "setext";
+		case "code": return next.fenceChar !== void 0 || next.lang !== void 0;
+		default: return false;
+	}
+};
+/**
+* Whether `prev` and `next` may sit on adjacent lines with no blank line
+* between them without either absorbing the other on re-parse. Drives tight
+* list items; anything not provably safe takes the blank line.
+*/
+const canJoinWithoutBlank = (prev, next) => {
+	switch (prev.type) {
+		case "heading": return true;
+		case "thematicBreak": return true;
+		case "code":
+			if (prev.fenceChar !== void 0 || prev.lang !== void 0) return true;
+			return !(next.type === "code" && next.fenceChar === void 0 && next.lang === void 0);
+		case "paragraph": return interruptsParagraph(next);
+		case "blockquote": return next.type !== "blockquote" && next.type !== "paragraph" && interruptsParagraph(next);
+		default: return false;
+	}
+};
+/**
+* Serialize a sequence of flow blocks, handling sibling adjacency. With
+* `tight`, safe pairs join with a bare newline (tight-list items).
+*/
+const serializeBlocks = (children, state, tight = false) => {
+	const parts = [];
+	const nodes = [];
+	let previous;
+	let previousListMarker;
+	for (const child of children) {
+		guard(state, child);
+		switch (child.type) {
+			case "paragraph":
+				parts.push(serializeInlines(child.children, FLOW_CONTEXT, state, true));
+				previousListMarker = void 0;
+				break;
+			case "heading":
+				parts.push(serializeHeading(child, state));
+				previousListMarker = void 0;
+				break;
+			case "thematicBreak":
+				parts.push((child.markerChar ?? "*").repeat(3));
+				previousListMarker = void 0;
+				break;
+			case "code":
+				parts.push(serializeCode(child, previous?.type === "list"));
+				previousListMarker = void 0;
+				break;
+			case "html":
+				parts.push(child.value);
+				previousListMarker = void 0;
+				break;
+			case "blockquote": {
+				const inner = serializeBlocks(child.children, state);
+				parts.push(prefixLines(inner, "> ", ">"));
+				previousListMarker = void 0;
+				break;
+			}
+			case "list": {
+				const flipped = previousListMarker !== void 0 && previousListMarker === effectiveListMarker(child, false);
+				parts.push(serializeList(child, state, flipped));
+				previousListMarker = effectiveListMarker(child, flipped);
+				break;
+			}
+			case "definition":
+				parts.push(serializeDefinition(child));
+				previousListMarker = void 0;
+				break;
+			case "footnoteDefinition":
+				parts.push(serializeFootnoteDefinition(child, state));
+				previousListMarker = void 0;
+				break;
+			case "table":
+				parts.push(serializeTable(child, state));
+				previousListMarker = void 0;
+				break;
+			case "frontmatter": {
+				const open = child.format === "toml" ? "+++" : child.format === "json" ? "---json" : "---";
+				const close = child.format === "toml" ? "+++" : "---";
+				parts.push(child.value === "" ? `${open}\n${close}` : `${open}\n${child.value}\n${close}`);
+				previousListMarker = void 0;
+				break;
+			}
+		}
+		previous = child;
+		nodes.push(child);
+		unguard(state);
+	}
+	if (!tight) return parts.join("\n\n");
+	let out = "";
+	for (let index = 0; index < parts.length; index += 1) {
+		if (index > 0) {
+			const prev = nodes[index - 1];
+			const next = nodes[index];
+			out += canJoinWithoutBlank(prev, next) ? "\n" : "\n\n";
+		}
+		out += parts[index];
+	}
+	return out;
+};
+/**
+* Serialize a document tree to canonical markdown source.
+*
+* Throws the raw `GuardExceeded` carrier when the tree nests past
+* `MAX_NESTING_DEPTH`; the facade materializes the typed error. Output is
+* empty for an empty root and ends with exactly one newline otherwise.
+*/
+const stringifyTree = (root) => {
+	const body = serializeBlocks(root.children, { depth: 0 });
+	return body === "" ? "" : `${body}\n`;
+};
+
+//#endregion
+export { stringifyTree };

package/internal/unescape.js

@@ -0,0 +1,18 @@
+import { decodeEntity } from "./entities.js";
+
+//#region src/internal/unescape.ts
+/** The punctuation set a backslash may escape, per the spec. */
+const ESCAPABLE = "[!\"#$%&'()*+,./:;<=>?@[\\\\\\]^_`{|}~-]";
+/** One entity, in any of the three spec forms. */
+const ENTITY = "&(?:#x[a-f0-9]{1,6}|#[0-9]{1,7}|[a-z][a-z0-9]{1,31});";
+const reBackslashOrAmp = /[\\&]/;
+const reEntityOrEscapedChar = new RegExp(`\\\\${ESCAPABLE}|${ENTITY}`, "gi");
+const unescapeChar = (source) => {
+	if (source.charCodeAt(0) === 92) return source.charAt(1);
+	return decodeEntity(source) ?? source;
+};
+/** Replace every backslash escape and character reference with its literal. */
+const unescapeString = (source) => reBackslashOrAmp.test(source) ? source.replace(reEntityOrEscapedChar, unescapeChar) : source;
+
+//#endregion
+export { ENTITY, ESCAPABLE, unescapeString };

package/package.json

@@ -0,0 +1,61 @@
+{
+	"name": "@effected/markdown",
+	"version": "0.2.0",
+	"private": false,
+	"description": "CommonMark and GFM markdown parse, edit and transform schemas for Effect",
+	"keywords": [
+		"markdown",
+		"commonmark",
+		"gfm",
+		"mdast",
+		"parser",
+		"effect",
+		"schema",
+		"effected"
+	],
+	"homepage": "https://github.com/spencerbeggs/effected/tree/main/packages/markdown#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/effected/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/effected.git",
+		"directory": "packages/markdown"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"sideEffects": false,
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"peerDependencies": {
+		"@effected/jsonc": "0.4.0",
+		"@effected/toml": "0.2.0",
+		"@effected/yaml": "0.4.0",
+		"effect": "4.0.0-beta.99"
+	},
+	"peerDependenciesMeta": {
+		"@effected/jsonc": {
+			"optional": true
+		},
+		"@effected/toml": {
+			"optional": true
+		},
+		"@effected/yaml": {
+			"optional": true
+		}
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.11"
+    }
+  ]
+}