@serverkgg/bridge 0.0.1 → 0.0.2

package/src/guides/compile.ts

@@ -0,0 +1,193 @@
+import { verifyAsset } from "../manifest/assets";
+import type { GuideEntry, GuideSurface, GuideTag } from "../manifest/guide";
+import type { LocalizedText } from "../manifest/localized";
+import type { GuidePackage, Manifest } from "../manifest/manifest";
+import type { PackageSource } from "../manifest/source";
+import type { GuideBlock, GuideLeafBlock } from "./blocks";
+import { type CompiledGuide, type CompiledGuideTag, compiledGuideSchema } from "./compiled";
+import { type ParsedBlock, type ParsedLeafBlock, parseGuideMarkdown } from "./markdown";
+
+export interface GuideImageAsset {
+	path: string;
+	bytes: Uint8Array;
+	mediaType: string;
+	width: number | null;
+	height: number | null;
+}
+
+export interface DraftGuide {
+	id: string;
+	title: LocalizedText;
+	summary: LocalizedText;
+	tags: CompiledGuideTag[];
+	surfaces: GuideSurface[];
+	videoId: string | null;
+	body: {
+		ar: ParsedBlock[];
+		en: ParsedBlock[];
+	};
+}
+
+export interface GuidePack {
+	drafts: DraftGuide[];
+	files: string[];
+	images: GuideImageAsset[];
+	commands: string[];
+}
+
+const compileTags = (guideTags: GuideTag[], tags: string[]): CompiledGuideTag[] => {
+	return tags.map((tag) => {
+		const order = guideTags.findIndex((declared) => declared.id === tag);
+		const declared = guideTags[order];
+
+		if (!declared) {
+			throw new Error(`tag "${tag}" is not declared in guideTags`);
+		}
+
+		return {
+			id: declared.id,
+			name: declared.name,
+			order,
+		};
+	});
+};
+
+export const compileGuides = (source: PackageSource, guideTags: GuideTag[], entries: GuideEntry[]): GuidePack => {
+	const drafts: DraftGuide[] = [];
+	const files: string[] = [];
+	const commands: string[] = [];
+	const imageByPath = new Map<string, GuideImageAsset>();
+
+	const readBody = (path: string) => {
+		const body = source.read(path);
+
+		if (!body) {
+			throw new Error(`missing guide body ${path}`);
+		}
+
+		files.push(path);
+
+		const parsed = parseGuideMarkdown(path, new TextDecoder().decode(body));
+
+		commands.push(...parsed.commands);
+
+		for (const imagePath of parsed.images) {
+			if (imageByPath.has(imagePath)) {
+				continue;
+			}
+
+			const imageBytes = source.read(imagePath);
+
+			if (!imageBytes) {
+				throw new Error(`missing guide image ${imagePath}`);
+			}
+
+			const verified = verifyAsset(imagePath, imageBytes);
+
+			imageByPath.set(imagePath, {
+				path: imagePath,
+				bytes: imageBytes,
+				mediaType: verified.mediaType,
+				width: verified.dimensions?.width ?? null,
+				height: verified.dimensions?.height ?? null,
+			});
+		}
+
+		return parsed.blocks;
+	};
+
+	for (const entry of entries) {
+		drafts.push({
+			id: entry.id,
+			title: entry.title,
+			summary: entry.summary,
+			tags: compileTags(guideTags, entry.tags),
+			surfaces: entry.surfaces,
+			videoId: entry.video ?? null,
+			body: {
+				ar: readBody(entry.bodyPath.ar),
+				en: readBody(entry.bodyPath.en),
+			},
+		});
+	}
+
+	return {
+		drafts,
+		files: [
+			...files,
+			...imageByPath.keys(),
+		],
+		images: [
+			...imageByPath.values(),
+		],
+		commands,
+	};
+};
+
+export const readGuidePack = (source: PackageSource, manifest: Manifest): GuidePack | null => {
+	if (manifest.guides.length === 0) {
+		return null;
+	}
+
+	return compileGuides(source, manifest.guideTags, manifest.guides);
+};
+
+export const readGuidePackage = (source: PackageSource, document: GuidePackage): GuidePack => {
+	return compileGuides(source, document.guideTags, document.guides);
+};
+
+export interface ResolvedGuideImage {
+	url: string;
+	width: number | null;
+	height: number | null;
+}
+
+export const resolveGuideImages = (
+	drafts: DraftGuide[],
+	resolved: Map<string, ResolvedGuideImage>,
+): CompiledGuide[] => {
+	const resolveLeaf = (block: ParsedLeafBlock): GuideLeafBlock => {
+		if (block.type !== "image") {
+			return block;
+		}
+
+		const image = resolved.get(block.path);
+
+		if (!image) {
+			throw new Error(`unresolved guide image ${block.path}`);
+		}
+
+		return {
+			type: "image",
+			url: image.url,
+			alt: block.alt,
+			width: image.width,
+			height: image.height,
+		};
+	};
+
+	const resolveBlocks = (blocks: ParsedBlock[]): GuideBlock[] => {
+		return blocks.map((block) => {
+			if (block.type !== "conditional") {
+				return resolveLeaf(block);
+			}
+
+			return {
+				type: "conditional",
+				key: block.key,
+				when: block.when.map(resolveLeaf),
+				otherwise: block.otherwise.map(resolveLeaf),
+			};
+		});
+	};
+
+	return drafts.map((draft) => {
+		return compiledGuideSchema.parse({
+			...draft,
+			body: {
+				ar: resolveBlocks(draft.body.ar),
+				en: resolveBlocks(draft.body.en),
+			},
+		});
+	});
+};

package/src/guides/compiled.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { GuideSurface, guideTagSchema, zYoutubeId } from "../manifest/guide";
+import { localizedTextSchema } from "../manifest/localized";
+import { zSlug } from "../manifest/primitives";
+import { guideBlockSchema } from "./blocks";
+
+export const GUIDE_BODY_MAX_BLOCKS = 400;
+
+export const compiledGuideTagSchema = guideTagSchema.extend({
+	order: z.int().nonnegative(),
+});
+
+export type CompiledGuideTag = z.infer<typeof compiledGuideTagSchema>;
+
+export const compiledGuideSchema = z.object({
+	id: zSlug,
+	title: localizedTextSchema,
+	summary: localizedTextSchema,
+	tags: z.array(compiledGuideTagSchema).max(8).default([]),
+	surfaces: z.array(z.enum(GuideSurface)).max(8).default([]),
+	videoId: zYoutubeId.nullable(),
+	body: z.object({
+		ar: z.array(guideBlockSchema).min(1).max(GUIDE_BODY_MAX_BLOCKS),
+		en: z.array(guideBlockSchema).min(1).max(GUIDE_BODY_MAX_BLOCKS),
+	}),
+});
+
+export type CompiledGuide = z.infer<typeof compiledGuideSchema>;

package/src/guides/index.ts

@@ -0,0 +1,6 @@
+export * from "./blocks";
+export * from "./compile";
+export * from "./compiled";
+export * from "./markdown";
+export * from "./variables";
+export * from "./version";

package/src/guides/markdown.test.ts

@@ -0,0 +1,374 @@
+import { describe, expect, test } from "bun:test";
+import { GuideOpenTab } from "./blocks";
+import { parseGuideMarkdown } from "./markdown";
+
+const parse = (text: string) => parseGuideMarkdown("guides/test/en.md", text);
+
+describe("static blocks", () => {
+	test("parses the existing block vocabulary", () => {
+		const { blocks } = parse(
+			[
+				"## Join the game",
+				"",
+				"Copy the address and paste it in.",
+				"",
+				"1. Open **Multiplayer**",
+				"2. Click **Add Server**",
+				"",
+				"```txt",
+				"say hello",
+				"```",
+				"",
+				"> [!note] The first start takes a moment.",
+			].join("\n"),
+		);
+
+		expect(blocks.map((block) => block.type)).toEqual([
+			"heading",
+			"paragraph",
+			"list",
+			"code",
+			"callout",
+		]);
+	});
+
+	test("still rejects what it always rejected", () => {
+		expect(() => parse("# Title")).toThrow(/h1 is not supported/);
+		expect(() => parse("| a | b |")).toThrow(/tables are not supported/);
+		expect(() => parse("<div>hi</div>")).toThrow(/raw HTML/);
+		expect(() => parse("---")).toThrow(/horizontal rules/);
+	});
+});
+
+describe("variables", () => {
+	test("parses an inline variable", () => {
+		const { blocks } = parse("Your address is {{server.address}} — paste it in.");
+
+		expect(blocks[0]).toEqual({
+			type: "paragraph",
+			children: [
+				{
+					type: "text",
+					text: "Your address is ",
+				},
+				{
+					type: "variable",
+					key: "server.address",
+				},
+				{
+					type: "text",
+					text: " — paste it in.",
+				},
+			],
+		});
+	});
+
+	test("accepts a panel variable", () => {
+		const { blocks } = parse("The motd is {{panel.MOTD}}.");
+
+		expect(blocks[0]).toMatchObject({
+			children: expect.arrayContaining([
+				{
+					type: "variable",
+					key: "panel.MOTD",
+				},
+			]),
+		});
+	});
+
+	test("rejects an unknown key", () => {
+		expect(() => parse("Your address is {{server.adress}}.")).toThrow(/unknown variable "server.adress"/);
+	});
+
+	test("rejects a lowercase panel key", () => {
+		expect(() => parse("{{panel.motd}} is set.")).toThrow(/unknown variable/);
+	});
+
+	test("rejects an unterminated marker", () => {
+		expect(() => parse("Your address is {{server.address.")).toThrow(/unterminated \{\{ marker/);
+	});
+
+	test("rejects a variable inside a link target", () => {
+		expect(() => parse("See [your server](/server/{{server.code}}).")).toThrow(
+			/variables cannot be used inside a link target/,
+		);
+	});
+});
+
+describe("directives", () => {
+	test("parses a field", () => {
+		const { blocks } = parse("@[field](server.address)");
+
+		expect(blocks[0]).toEqual({
+			type: "field",
+			key: "server.address",
+		});
+	});
+
+	test("rejects a field with an unknown key", () => {
+		expect(() => parse("@[field](server.nope)")).toThrow(/unknown variable "server.nope"/);
+	});
+
+	test("parses a command and collects it", () => {
+		const result = parse("@[command](whitelist on)");
+
+		expect(result.blocks[0]).toEqual({
+			type: "command",
+			command: "whitelist on",
+		});
+		expect(result.commands).toEqual([
+			"whitelist on",
+		]);
+	});
+
+	test("rejects an empty command", () => {
+		expect(() => parse("@[command]()")).toThrow(/a command must be a single line/);
+	});
+
+	test("parses every open target", () => {
+		const { blocks } = parse(
+			[
+				"@[open](console)",
+				"@[open](backups)",
+				"@[open](files:server.properties)",
+				"@[open](files)",
+				"@[open](panel:mods)",
+			].join("\n"),
+		);
+
+		expect(blocks).toEqual([
+			{
+				type: "open",
+				target: {
+					tab: GuideOpenTab.Console,
+				},
+			},
+			{
+				type: "open",
+				target: {
+					tab: GuideOpenTab.Backups,
+				},
+			},
+			{
+				type: "open",
+				target: {
+					tab: GuideOpenTab.Files,
+					path: "server.properties",
+				},
+			},
+			{
+				type: "open",
+				target: {
+					tab: GuideOpenTab.Files,
+					path: null,
+				},
+			},
+			{
+				type: "open",
+				target: {
+					tab: GuideOpenTab.Panel,
+					tabId: "mods",
+				},
+			},
+		]);
+	});
+
+	test("rejects a panel target without a tab id", () => {
+		expect(() => parse("@[open](panel)")).toThrow(/panel target needs a tab id/);
+	});
+
+	test("rejects an unknown open target", () => {
+		expect(() => parse("@[open](nowhere)")).toThrow(/unknown open target "nowhere"/);
+	});
+
+	test("rejects a traversing file path", () => {
+		expect(() => parse("@[open](files:../../etc/passwd)")).toThrow();
+	});
+
+	test("rejects an unknown directive", () => {
+		expect(() => parse("@[embed](something)")).toThrow(/unknown directive @\[embed\]/);
+	});
+
+	test("keeps the youtube directive working", () => {
+		const { blocks } = parse("@[youtube](dQw4w9WgXcQ)");
+
+		expect(blocks[0]).toEqual({
+			type: "youtube",
+			videoId: "dQw4w9WgXcQ",
+		});
+	});
+
+	test("does not swallow a directive into the paragraph above it", () => {
+		const { blocks } = parse(
+			[
+				"Copy your address:",
+				"@[field](server.address)",
+			].join("\n"),
+		);
+
+		expect(blocks.map((block) => block.type)).toEqual([
+			"paragraph",
+			"field",
+		]);
+	});
+});
+
+describe("conditionals", () => {
+	test("parses both branches", () => {
+		const { blocks } = parse(
+			[
+				":::when server.address",
+				"Paste this into the game:",
+				"",
+				"@[field](server.address)",
+				":::else",
+				"Your server is still setting up.",
+				":::",
+			].join("\n"),
+		);
+
+		expect(blocks).toEqual([
+			{
+				type: "conditional",
+				key: "server.address",
+				when: [
+					{
+						type: "paragraph",
+						children: [
+							{
+								type: "text",
+								text: "Paste this into the game:",
+							},
+						],
+					},
+					{
+						type: "field",
+						key: "server.address",
+					},
+				],
+				otherwise: [
+					{
+						type: "paragraph",
+						children: [
+							{
+								type: "text",
+								text: "Your server is still setting up.",
+							},
+						],
+					},
+				],
+			},
+		]);
+	});
+
+	test("allows a missing else branch", () => {
+		const { blocks } = parse(
+			[
+				":::when server.address",
+				"@[field](server.address)",
+				":::",
+			].join("\n"),
+		);
+
+		expect(blocks[0]).toMatchObject({
+			type: "conditional",
+			otherwise: [],
+		});
+	});
+
+	test("keeps blocks around a conditional", () => {
+		const { blocks } = parse(
+			[
+				"## Join the game",
+				"",
+				":::when server.address",
+				"@[field](server.address)",
+				":::",
+				"",
+				"Have fun.",
+			].join("\n"),
+		);
+
+		expect(blocks.map((block) => block.type)).toEqual([
+			"heading",
+			"conditional",
+			"paragraph",
+		]);
+	});
+
+	test("parses two conditionals in a row", () => {
+		const { blocks } = parse(
+			[
+				":::when server.address",
+				"one",
+				":::",
+				":::when server.playersMax",
+				"two",
+				":::",
+			].join("\n"),
+		);
+
+		expect(blocks.map((block) => block.type)).toEqual([
+			"conditional",
+			"conditional",
+		]);
+	});
+
+	test("rejects nesting", () => {
+		expect(() =>
+			parse(
+				[
+					":::when server.address",
+					":::when server.host",
+					"nope",
+					":::",
+					":::",
+				].join("\n"),
+			),
+		).toThrow(/conditionals cannot be nested/);
+	});
+
+	test("rejects an unterminated block", () => {
+		expect(() =>
+			parse(
+				[
+					":::when server.address",
+					"@[field](server.address)",
+				].join("\n"),
+			),
+		).toThrow(/unterminated :::when block/);
+	});
+
+	test("rejects an empty when branch", () => {
+		expect(() =>
+			parse(
+				[
+					":::when server.address",
+					":::else",
+					"nothing",
+					":::",
+				].join("\n"),
+			),
+		).toThrow(/empty :::when branch/);
+	});
+
+	test("rejects a stray close", () => {
+		expect(() => parse(":::")).toThrow(/unexpected ::: without a matching :::when/);
+	});
+
+	test("rejects an unknown key", () => {
+		expect(() =>
+			parse(
+				[
+					":::when server.nope",
+					"hi",
+					":::",
+				].join("\n"),
+			),
+		).toThrow(/unknown variable "server.nope"/);
+	});
+
+	test("rejects a malformed opener", () => {
+		expect(() => parse(":::if server.address")).toThrow(/conditionals open with :::when/);
+	});
+});