@serverkgg/bridge 0.0.1 → 0.0.2

package/src/guides/markdown.ts

@@ -0,0 +1,769 @@
+import {
+	GUIDE_COMMAND_MAX_LENGTH,
+	GuideCalloutTone,
+	type GuideInline,
+	type GuideLeafBlock,
+	GuideOpenTab,
+	type GuideOpenTarget,
+	guideOpenTargetSchema,
+	zGuideCommand,
+} from "./blocks";
+import { isGuideVariableKey, isPanelVariableKey } from "./variables";
+
+const CALLOUT_TONES: Record<string, GuideCalloutTone> = {
+	note: GuideCalloutTone.Note,
+	warning: GuideCalloutTone.Warning,
+	danger: GuideCalloutTone.Danger,
+};
+
+export interface ParsedImage {
+	type: "image";
+	path: string;
+	alt: string;
+}
+
+export type ParsedLeafBlock =
+	| Exclude<
+			GuideLeafBlock,
+			{
+				type: "image";
+			}
+	  >
+	| ParsedImage;
+
+export interface ParsedConditional {
+	type: "conditional";
+	key: string;
+	when: ParsedLeafBlock[];
+	otherwise: ParsedLeafBlock[];
+}
+
+export type ParsedBlock = ParsedLeafBlock | ParsedConditional;
+
+export interface ParsedGuideBody {
+	blocks: ParsedBlock[];
+	images: string[];
+	commands: string[];
+}
+
+const FENCE_PATTERN = /^```([a-z0-9-]*)$/;
+
+const HEADING_2_PATTERN = /^##\s+(.+)$/;
+
+const HEADING_3_PATTERN = /^###\s+(.+)$/;
+
+const CALLOUT_OPEN_PATTERN = /^>\s*\[!(note|warning|danger)\]\s*(.*)$/;
+
+const IMAGE_LINE_PATTERN = /^!\[([^\]]*)\]\(([^)\s]+)\)$/;
+
+const IMAGE_PATH_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9/_-]*\.webp$/;
+
+const DIRECTIVE_LINE_PATTERN = /^@\[([a-z]+)\]\((.*)\)$/;
+
+const YOUTUBE_ID_PATTERN = /^[A-Za-z0-9_-]{11}$/;
+
+const UNORDERED_ITEM_PATTERN = /^-\s+(.+)$/;
+
+const ORDERED_ITEM_PATTERN = /^\d{1,3}\.\s+(.+)$/;
+
+const RULE_PATTERN = /^(-{3,}|\*{3,}|_{3,})$/;
+
+const RAW_HTML_PATTERN = /<[a-zA-Z!/]/;
+
+const INLINE_IMAGE_PATTERN = /^!\[[^\]]*\]\([^)\s]+\)/;
+
+const LINK_PATTERN = /^\[([^\]]+)\]\(([^)\s]+)\)/;
+
+const LINK_HREF_PATTERN = /^(https:\/\/|\/)/;
+
+const CONDITIONAL_OPEN_PATTERN = /^:::when\s+(\S+)$/;
+
+const CONDITIONAL_ELSE = ":::else";
+
+const CONDITIONAL_CLOSE = ":::";
+
+const fail: (path: string, line: number, message: string) => never = (path, line, message) => {
+	throw new Error(`${path}:${line} ${message}`);
+};
+
+const checkVariableRef = (path: string, line: number, key: string) => {
+	if (!isGuideVariableKey(key) && !isPanelVariableKey(key)) {
+		fail(path, line, `unknown variable "${key}"`);
+	}
+
+	return key;
+};
+
+const parseInlines = (path: string, line: number, text: string): GuideInline[] => {
+	if (RAW_HTML_PATTERN.test(text)) {
+		fail(path, line, "raw HTML is not supported");
+	}
+
+	const inlines: GuideInline[] = [];
+
+	let plain = "";
+	let index = 0;
+
+	const flush = () => {
+		if (plain.length > 0) {
+			inlines.push({
+				type: "text",
+				text: plain,
+			});
+
+			plain = "";
+		}
+	};
+
+	while (index < text.length) {
+		if (text.startsWith("{{", index)) {
+			const end = text.indexOf("}}", index + 2);
+
+			if (end === -1) {
+				fail(path, line, "unterminated {{ marker");
+			}
+
+			const key = text.slice(index + 2, end).trim();
+
+			if (key.length === 0) {
+				fail(path, line, "empty {{ marker");
+			}
+
+			checkVariableRef(path, line, key);
+
+			flush();
+			inlines.push({
+				type: "variable",
+				key,
+			});
+
+			index = end + 2;
+
+			continue;
+		}
+
+		if (text.startsWith("**", index)) {
+			const end = text.indexOf("**", index + 2);
+
+			if (end === -1) {
+				fail(path, line, "unterminated ** marker");
+			}
+
+			const inner = text.slice(index + 2, end);
+
+			if (inner.trim().length === 0) {
+				fail(path, line, "empty ** marker");
+			}
+
+			flush();
+			inlines.push({
+				type: "bold",
+				text: inner,
+			});
+
+			index = end + 2;
+
+			continue;
+		}
+
+		const char = text[index];
+
+		if (char === "*") {
+			const end = text.indexOf("*", index + 1);
+
+			if (end === -1) {
+				fail(path, line, "unterminated * marker");
+			}
+
+			const inner = text.slice(index + 1, end);
+
+			if (inner.trim().length === 0) {
+				fail(path, line, "empty * marker");
+			}
+
+			flush();
+			inlines.push({
+				type: "italic",
+				text: inner,
+			});
+
+			index = end + 1;
+
+			continue;
+		}
+
+		if (char === "`") {
+			const end = text.indexOf("`", index + 1);
+
+			if (end === -1) {
+				fail(path, line, "unterminated ` marker");
+			}
+
+			const inner = text.slice(index + 1, end);
+
+			if (inner.length === 0) {
+				fail(path, line, "empty ` marker");
+			}
+
+			flush();
+			inlines.push({
+				type: "code",
+				text: inner,
+			});
+
+			index = end + 1;
+
+			continue;
+		}
+
+		if (char === "!" && INLINE_IMAGE_PATTERN.test(text.slice(index))) {
+			fail(path, line, "images must stand on their own line");
+		}
+
+		if (char === "[") {
+			const match = text.slice(index).match(LINK_PATTERN);
+
+			if (!match) {
+				fail(path, line, "unterminated link");
+			}
+
+			const [full, label, href] = match;
+
+			if (!label || !href || !full) {
+				fail(path, line, "malformed link");
+			}
+
+			if (!LINK_HREF_PATTERN.test(href)) {
+				fail(path, line, `link "${href}" must start with https:// or /`);
+			}
+
+			if (href.includes("{{")) {
+				fail(path, line, "variables cannot be used inside a link target");
+			}
+
+			flush();
+			inlines.push({
+				type: "link",
+				href,
+				text: label,
+			});
+
+			index += full.length;
+
+			continue;
+		}
+
+		plain += char;
+		index += 1;
+	}
+
+	flush();
+
+	if (inlines.length === 0) {
+		fail(path, line, "empty text run");
+	}
+
+	return inlines;
+};
+
+const inlineText = (inlines: GuideInline[]) => {
+	return inlines.map((inline) => (inline.type === "variable" ? "" : inline.text)).join(" ");
+};
+
+const headingId = (inlines: GuideInline[], used: Map<string, number>, fallback: string) => {
+	const base =
+		inlineText(inlines)
+			.toLowerCase()
+			.replace(/[^\p{L}\p{N}]+/gu, "-")
+			.replace(/^-+|-+$/g, "")
+			.slice(0, 96) || fallback;
+
+	const count = used.get(base) ?? 0;
+
+	used.set(base, count + 1);
+
+	return count === 0 ? base : `${base}-${count + 1}`;
+};
+
+const parseOpenTarget = (path: string, line: number, value: string): GuideOpenTarget => {
+	const separator = value.indexOf(":");
+	const tab = separator === -1 ? value : value.slice(0, separator);
+	const argument = separator === -1 ? null : value.slice(separator + 1);
+
+	if (tab === GuideOpenTab.Panel) {
+		if (!argument) {
+			fail(path, line, "panel target needs a tab id, for example panel:settings");
+		}
+
+		return guideOpenTargetSchema.parse({
+			tab,
+			tabId: argument,
+		});
+	}
+
+	if (tab === GuideOpenTab.Files) {
+		return guideOpenTargetSchema.parse({
+			tab,
+			path: argument,
+		});
+	}
+
+	if (argument !== null) {
+		fail(path, line, `"${tab}" target does not take an argument`);
+	}
+
+	if (tab !== GuideOpenTab.Overview && tab !== GuideOpenTab.Console && tab !== GuideOpenTab.Backups) {
+		fail(path, line, `unknown open target "${value}"`);
+	}
+
+	return guideOpenTargetSchema.parse({
+		tab,
+	});
+};
+
+const isBlockStart = (line: string) => {
+	return (
+		line.startsWith("#")
+		|| line.startsWith("```")
+		|| line.startsWith(">")
+		|| line.startsWith("|")
+		|| line.startsWith(":::")
+		|| RULE_PATTERN.test(line)
+		|| UNORDERED_ITEM_PATTERN.test(line)
+		|| ORDERED_ITEM_PATTERN.test(line)
+		|| IMAGE_LINE_PATTERN.test(line)
+		|| DIRECTIVE_LINE_PATTERN.test(line)
+	);
+};
+
+interface Scanner {
+	path: string;
+	lines: string[];
+	index: number;
+	headingIds: Map<string, number>;
+	images: string[];
+	commands: string[];
+}
+
+const scanLeafBlocks = (scanner: Scanner, nested: boolean): ParsedLeafBlock[] => {
+	const { path } = scanner;
+	const blocks: ParsedLeafBlock[] = [];
+
+	while (scanner.index < scanner.lines.length) {
+		const raw = scanner.lines[scanner.index];
+
+		if (raw === undefined) {
+			break;
+		}
+
+		const lineNumber = scanner.index + 1;
+		const line = raw.trimEnd();
+
+		if (line.trim().length === 0) {
+			scanner.index += 1;
+
+			continue;
+		}
+
+		if (/^\s/.test(line)) {
+			fail(path, lineNumber, "indented blocks are not supported");
+		}
+
+		if (line === CONDITIONAL_ELSE || line === CONDITIONAL_CLOSE) {
+			if (!nested) {
+				fail(path, lineNumber, `unexpected ${line} without a matching :::when`);
+			}
+
+			break;
+		}
+
+		if (CONDITIONAL_OPEN_PATTERN.test(line)) {
+			if (nested) {
+				fail(path, lineNumber, "conditionals cannot be nested");
+			}
+
+			break;
+		}
+
+		if (line.startsWith(":::")) {
+			fail(path, lineNumber, "conditionals open with :::when <variable>");
+		}
+
+		if (line.startsWith("```")) {
+			const fence = line.match(FENCE_PATTERN);
+
+			if (!fence) {
+				fail(path, lineNumber, "malformed code fence");
+			}
+
+			const language = fence[1] ? fence[1] : null;
+			const content: string[] = [];
+
+			scanner.index += 1;
+
+			let closed = false;
+
+			while (scanner.index < scanner.lines.length) {
+				const codeLine = scanner.lines[scanner.index];
+
+				if (codeLine === undefined) {
+					break;
+				}
+
+				if (codeLine.trimEnd() === "```") {
+					closed = true;
+					scanner.index += 1;
+
+					break;
+				}
+
+				content.push(codeLine);
+				scanner.index += 1;
+			}
+
+			if (!closed) {
+				fail(path, lineNumber, "unterminated code fence");
+			}
+
+			const body = content.join("\n").trimEnd();
+
+			if (body.length === 0) {
+				fail(path, lineNumber, "empty code fence");
+			}
+
+			blocks.push({
+				type: "code",
+				language,
+				content: body,
+			});
+
+			continue;
+		}
+
+		if (line.startsWith("#")) {
+			const h3 = line.match(HEADING_3_PATTERN);
+			const h2 = h3 ? null : line.match(HEADING_2_PATTERN);
+			const match = h3 ?? h2;
+
+			if (!match?.[1]) {
+				if (/^#\s/.test(line)) {
+					fail(path, lineNumber, "h1 is not supported; the guide title comes from serverk.yml");
+				}
+
+				fail(path, lineNumber, "unsupported heading depth; use ## or ###");
+			}
+
+			const children = parseInlines(path, lineNumber, match[1].trim());
+
+			blocks.push({
+				type: "heading",
+				level: h3 ? 3 : 2,
+				id: headingId(children, scanner.headingIds, `section-${scanner.headingIds.size + 1}`),
+				children,
+			});
+
+			scanner.index += 1;
+
+			continue;
+		}
+
+		if (RULE_PATTERN.test(line)) {
+			fail(path, lineNumber, "horizontal rules are not supported");
+		}
+
+		if (line.startsWith("|")) {
+			fail(path, lineNumber, "tables are not supported");
+		}
+
+		if (line.startsWith(">")) {
+			const open = line.match(CALLOUT_OPEN_PATTERN);
+
+			if (!open?.[1]) {
+				fail(path, lineNumber, "blockquotes must open with > [!note], > [!warning] or > [!danger]");
+			}
+
+			const parts: string[] = [];
+
+			if (open[2]) {
+				parts.push(open[2]);
+			}
+
+			scanner.index += 1;
+
+			while (scanner.index < scanner.lines.length) {
+				const quoted = scanner.lines[scanner.index]?.trimEnd();
+
+				if (quoted === undefined || !quoted.startsWith(">")) {
+					break;
+				}
+
+				parts.push(quoted.replace(/^>\s?/, ""));
+				scanner.index += 1;
+			}
+
+			const content = parts.join(" ").trim();
+
+			if (content.length === 0) {
+				fail(path, lineNumber, "empty callout");
+			}
+
+			const tone = CALLOUT_TONES[open[1]];
+
+			if (!tone) {
+				fail(path, lineNumber, "unknown callout tone");
+			}
+
+			blocks.push({
+				type: "callout",
+				tone,
+				children: parseInlines(path, lineNumber, content),
+			});
+
+			continue;
+		}
+
+		const image = line.match(IMAGE_LINE_PATTERN);
+
+		if (image) {
+			const [, alt, imagePath] = image;
+
+			if (imagePath === undefined || alt === undefined) {
+				fail(path, lineNumber, "malformed image");
+			}
+
+			if (!IMAGE_PATH_PATTERN.test(imagePath)) {
+				fail(path, lineNumber, `image "${imagePath}" must be a relative .webp path`);
+			}
+
+			blocks.push({
+				type: "image",
+				path: imagePath,
+				alt,
+			});
+			scanner.images.push(imagePath);
+
+			scanner.index += 1;
+
+			continue;
+		}
+
+		const directive = line.match(DIRECTIVE_LINE_PATTERN);
+
+		if (directive) {
+			const [, name, value] = directive;
+
+			if (!name || value === undefined) {
+				fail(path, lineNumber, "malformed directive");
+			}
+
+			switch (name) {
+				case "youtube": {
+					if (!YOUTUBE_ID_PATTERN.test(value)) {
+						fail(path, lineNumber, `"${value}" is not a YouTube video id`);
+					}
+
+					blocks.push({
+						type: "youtube",
+						videoId: value,
+					});
+
+					break;
+				}
+				case "field": {
+					blocks.push({
+						type: "field",
+						key: checkVariableRef(path, lineNumber, value.trim()),
+					});
+
+					break;
+				}
+				case "command": {
+					const command = zGuideCommand.safeParse(value.trim());
+
+					if (!command.success) {
+						fail(path, lineNumber, `a command must be a single line of 1 to ${GUIDE_COMMAND_MAX_LENGTH} characters`);
+					}
+
+					blocks.push({
+						type: "command",
+						command: command.data,
+					});
+					scanner.commands.push(command.data);
+
+					break;
+				}
+				case "open": {
+					blocks.push({
+						type: "open",
+						target: parseOpenTarget(path, lineNumber, value.trim()),
+					});
+
+					break;
+				}
+				default: {
+					fail(path, lineNumber, `unknown directive @[${name}]`);
+				}
+			}
+
+			scanner.index += 1;
+
+			continue;
+		}
+
+		if (line.startsWith("![") || line.startsWith("@[")) {
+			fail(path, lineNumber, "malformed image or directive line");
+		}
+
+		const unordered = line.match(UNORDERED_ITEM_PATTERN);
+		const ordered = unordered ? null : line.match(ORDERED_ITEM_PATTERN);
+
+		if (unordered || ordered) {
+			const pattern = unordered ? UNORDERED_ITEM_PATTERN : ORDERED_ITEM_PATTERN;
+			const items: GuideInline[][] = [];
+
+			while (scanner.index < scanner.lines.length) {
+				const itemLine = scanner.lines[scanner.index]?.trimEnd();
+
+				if (itemLine === undefined) {
+					break;
+				}
+
+				const item = itemLine.match(pattern);
+
+				if (!item?.[1]) {
+					break;
+				}
+
+				items.push(parseInlines(path, scanner.index + 1, item[1].trim()));
+				scanner.index += 1;
+			}
+
+			blocks.push({
+				type: "list",
+				ordered: Boolean(ordered),
+				items,
+			});
+
+			continue;
+		}
+
+		const parts: string[] = [
+			line,
+		];
+
+		scanner.index += 1;
+
+		while (scanner.index < scanner.lines.length) {
+			const next = scanner.lines[scanner.index]?.trimEnd();
+
+			if (next === undefined || next.trim().length === 0 || isBlockStart(next)) {
+				break;
+			}
+
+			if (/^\s/.test(next)) {
+				fail(path, scanner.index + 1, "indented blocks are not supported");
+			}
+
+			parts.push(next);
+			scanner.index += 1;
+		}
+
+		blocks.push({
+			type: "paragraph",
+			children: parseInlines(path, lineNumber, parts.join(" ")),
+		});
+	}
+
+	return blocks;
+};
+
+const scanBlocks = (scanner: Scanner): ParsedBlock[] => {
+	const { path } = scanner;
+	const blocks: ParsedBlock[] = [];
+
+	while (scanner.index < scanner.lines.length) {
+		const before = scanner.index;
+
+		blocks.push(...scanLeafBlocks(scanner, false));
+
+		if (scanner.index >= scanner.lines.length) {
+			break;
+		}
+
+		const lineNumber = scanner.index + 1;
+		const line = scanner.lines[scanner.index]?.trimEnd() ?? "";
+		const open = line.match(CONDITIONAL_OPEN_PATTERN);
+
+		if (!open?.[1]) {
+			if (scanner.index === before) {
+				fail(path, lineNumber, "unexpected line");
+			}
+
+			continue;
+		}
+
+		const key = checkVariableRef(path, lineNumber, open[1]);
+
+		scanner.index += 1;
+
+		const when = scanLeafBlocks(scanner, true);
+		const branch = scanner.lines[scanner.index]?.trimEnd();
+
+		if (branch === undefined) {
+			fail(path, lineNumber, "unterminated :::when block");
+		}
+
+		let otherwise: ParsedLeafBlock[] = [];
+
+		if (branch === CONDITIONAL_ELSE) {
+			scanner.index += 1;
+			otherwise = scanLeafBlocks(scanner, true);
+
+			const close = scanner.lines[scanner.index]?.trimEnd();
+
+			if (close !== CONDITIONAL_CLOSE) {
+				fail(path, lineNumber, "unterminated :::when block");
+			}
+		} else if (branch !== CONDITIONAL_CLOSE) {
+			fail(path, lineNumber, "unterminated :::when block");
+		}
+
+		scanner.index += 1;
+
+		if (when.length === 0) {
+			fail(path, lineNumber, "empty :::when branch");
+		}
+
+		blocks.push({
+			type: "conditional",
+			key,
+			when,
+			otherwise,
+		});
+	}
+
+	return blocks;
+};
+
+export const parseGuideMarkdown = (path: string, text: string): ParsedGuideBody => {
+	const scanner: Scanner = {
+		path,
+		lines: text.replace(/^/, "").split(/\r?\n/),
+		index: 0,
+		headingIds: new Map(),
+		images: [],
+		commands: [],
+	};
+
+	const blocks = scanBlocks(scanner);
+
+	if (blocks.length === 0) {
+		fail(path, 1, "guide body is empty");
+	}
+
+	return {
+		blocks,
+		images: scanner.images,
+		commands: scanner.commands,
+	};
+};