@kadal/prettier-plugin 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# @kadal/prettier-plugin
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```sh
+npm install --save-dev prettier @kadal/prettier-plugin
+```
+
+Part of [Kadal Deck](https://deck.kadal.cc/docs/). Prettier for decks: `deck.mdx` (and `slides.mdx`) formatted the way the engine reads them.
+
+```json
+// .prettierrc
+{ "plugins": ["@kadal/prettier-plugin"] }
+```
+
+That is all: with the plugin loaded, a file named `deck.mdx` or `slides.mdx` is formatted as a deck. Other deck files ask for it by parser:
+
+```json
+{
+  "plugins": ["@kadal/prettier-plugin"],
+  "overrides": [{ "files": ["slides/*.mdx", "talks/**/*.mdx"], "options": { "parser": "kadal-deck" } }]
+}
+```
+
+`kadal-deck format` (in `@kadal/deck`) runs the same formatter without any setup.
+
+## What it does
+
+- **Separators**: exactly `---` between slides and `----` for a slide beneath (a vertical stack), with one blank line around each. Pieces the engine skips (nothing in them) go.
+- **Headmatter and frontmatter**: the YAML through Prettier's YAML printer. Comments stay, keys stay in the order you wrote them, and the values are checked to be unchanged. A ```` ```yaml ```` block frontmatter stays a block.
+- **Slide bodies**: Prettier's Markdown printer (`-` bullets, `_emphasis_`, aligned tables, one blank line between blocks). Left exactly as written:
+  - code fences (with their `{2|3}` steps, `{monaco}`, titles), magic-move blocks
+  - `<Notes>` and the HTML-comment notes at the end of a slide
+  - `<style>` blocks
+  - `$$ … $$` maths
+  - `::right::` slot markers, `::code-group` … `::`, `<<< @/snippet` imports
+  - JSX and expressions
+- A thematic break is written `***`, since `---` would start a new slide.
+
+## Safety
+
+Prettier's Markdown printer reads MDX the way MDX 1 did; the engine compiles MDX 3. So every formatted slide is parsed again (CommonMark, and MDX 3 when the slide is valid MDX 3) and compared with the original as a syntax tree. A slide whose meaning would change keeps its text as written. The whole deck is then cut again and checked to have the same slides, stacked the same way, with the same frontmatter. If it does not, the formatter throws instead of writing.
+
+A slide containing `prettier-ignore` is left alone.
+
+## Options
+
+| Option | Default | |
+|---|---|---|
+| `kadalDeckBodies` | `true` | `false` formats the separators and the frontmatter only |
+
+`printWidth`, `tabWidth`, `useTabs`, `proseWrap`, `singleQuote`, `bracketSpacing` and `endOfLine` reach the YAML and Markdown printers as usual.
+
+## API
+
+```ts
+import * as prettier from "prettier";
+import { formatDeck } from "@kadal/prettier-plugin";
+
+const { text, changed, kept } = await formatDeck(source, prettier, { proseWrap: "preserve" });
+// kept: [{ slide, line, reason }] for each part left as written, and why
+```
+
+## Licence
+
+AGPL-3.0-or-later, like the engine (see [LICENSING.md](https://github.com/kadalcc/deck/blob/main/LICENSING.md)).

package/dist/format.d.ts

@@ -0,0 +1,68 @@
+//#region src/format.d.ts
+/**
+ * ─────────────────────────────────────────────────────────────────────────────
+ * FORMATTING A DECK
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * A deck is cut the engine's way (split.ts) and put back together with one spelling:
+ *
+ *   ---                      the headmatter: fenced YAML, nothing above it
+ *   title: …                 YAML through Prettier's YAML printer — comments kept, keys in the
+ *   ---                      order they were written, the values unchanged (checked)
+ *
+ *   # The first slide        each body through Prettier's Markdown (MDX) printer, with code,
+ *                            notes, magic-move, `<style>`, `::slot::` and the other sugar left
+ *   ---                      byte for byte (protect.ts), and the result checked to mean the
+ *   layout: center           same (guard.ts)
+ *   ---                      a separator: exactly `---`, or `----` for a slide beneath
+ *                            one blank line around every separator and after every frontmatter
+ *   # The next slide         one newline at the end of the file
+ *
+ * A ```yaml block frontmatter stays a block (its YAML is formatted the same way). A piece the
+ * engine skips — nothing in it, no frontmatter — goes. A thematic break Prettier would print as
+ * `---` (which would start a slide) is written `***`.
+ *
+ * Then the whole result is cut again and compared with the original: the same slides, stacked
+ * the same way, with the same frontmatter values. If not, nothing is returned but an error — a
+ * formatter that changes the deck is worse than none.
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+/** The part of Prettier this needs: `format`, so a caller can bring its own copy. */
+export interface PrettierLike {
+  format(source: string, options: Record<string, unknown>): Promise<string>;
+}
+/** The Prettier options that reach the YAML and Markdown printers. */
+export interface DeckFormatOptions {
+  printWidth?: number;
+  tabWidth?: number;
+  useTabs?: boolean;
+  proseWrap?: "always" | "never" | "preserve";
+  singleQuote?: boolean;
+  bracketSpacing?: boolean;
+  /** false: separators and frontmatter only; every body stays as written. Default true. */
+  bodies?: boolean;
+}
+export interface SlideReport {
+  /** 0-based slide index (as the engine counts: skipped pieces do not count). */
+  slide: number;
+  /** 1-based line of the slide in the original text. */
+  line: number;
+  /** Why the body (or the frontmatter) was left as written. */
+  reason: string;
+}
+export interface FormatResult {
+  text: string;
+  changed: boolean;
+  /** Slides some part of which was deliberately left as written, and why. */
+  kept: SlideReport[];
+}
+export declare class DeckFormatError extends Error {
+  name: string;
+}
+/**
+ * Format a deck's text. `prettier` is Prettier itself (or anything with its `format`). Throws a
+ * `DeckFormatError` when the result would not be the same deck — which the checks make a bug
+ * report, never a silent change.
+ */
+export declare function formatDeck(source: string, prettier: PrettierLike, options?: DeckFormatOptions): Promise<FormatResult>;
+//#endregion

package/dist/format.js

@@ -0,0 +1,197 @@
+import { mask, unmask } from "./protect.js";
+import { sameMeaning } from "./guard.js";
+import { cutDeck, isSlide, looksLikeYaml } from "./split.js";
+import YAML from "yaml";
+//#region src/format.ts
+var DeckFormatError = class extends Error {
+	name = "DeckFormatError";
+};
+const PASS_THROUGH = [
+	"printWidth",
+	"tabWidth",
+	"useTabs",
+	"proseWrap",
+	"singleQuote",
+	"bracketSpacing"
+];
+function innerOptions(options) {
+	const out = { endOfLine: "lf" };
+	for (const k of PASS_THROUGH) if (options[k] !== void 0) out[k] = options[k];
+	return out;
+}
+/** Leading and trailing blank lines off; trailing spaces off every line outside protected text. */
+const trimLines = (lines) => {
+	let a = 0;
+	let b = lines.length;
+	while (a < b && !lines[a].trim()) a++;
+	while (b > a && !lines[b - 1].trim()) b--;
+	return lines.slice(a, b);
+};
+async function formatYaml(yaml, kind, prettier, options) {
+	const asWritten = trimLines(yaml.split("\n")).join("\n");
+	let before;
+	try {
+		before = YAML.parse(yaml);
+	} catch {
+		return {
+			yaml: asWritten,
+			reason: "the frontmatter is not valid YAML"
+		};
+	}
+	let out;
+	try {
+		out = (await prettier.format(yaml, {
+			...innerOptions(options),
+			parser: "yaml"
+		})).replace(/\n+$/, "");
+	} catch {
+		return {
+			yaml: asWritten,
+			reason: "Prettier could not format the frontmatter"
+		};
+	}
+	let after;
+	try {
+		after = YAML.parse(out);
+	} catch {
+		return {
+			yaml: asWritten,
+			reason: "the formatted frontmatter did not parse"
+		};
+	}
+	if (JSON.stringify(before) !== JSON.stringify(after)) return {
+		yaml: asWritten,
+		reason: "formatting would change the frontmatter's values"
+	};
+	const lines = out.split("\n");
+	if (kind === "fence" && (!looksLikeYaml(lines) || lines.some((l) => /^-{3,}\s*$/.test(l)))) return {
+		yaml: asWritten,
+		reason: "the formatted frontmatter would not read as frontmatter"
+	};
+	return {
+		yaml: out,
+		reason: null
+	};
+}
+/** A byte-order mark, kept if the file had one. */
+const BOM = String.fromCharCode(65279);
+let nonceCounter = 0;
+const newNonce = () => `${Date.now().toString(36)}${(nonceCounter++).toString(36)}`;
+async function formatBody(body, prettier, options) {
+	const asWritten = trimLines(body.split("\n")).join("\n");
+	if (!asWritten) return {
+		body: "",
+		reason: null
+	};
+	if (options.bodies === false) return {
+		body: asWritten,
+		reason: null
+	};
+	if (asWritten.includes("prettier-ignore")) return {
+		body: asWritten,
+		reason: "it asks Prettier to leave it (prettier-ignore)"
+	};
+	const masked = mask(asWritten, newNonce());
+	let out;
+	try {
+		out = await prettier.format(masked.text, {
+			...innerOptions(options),
+			parser: "mdx",
+			embeddedLanguageFormatting: "off"
+		});
+	} catch (e) {
+		return {
+			body: asWritten,
+			reason: `Prettier could not parse it (${(e instanceof Error ? e.message : String(e)).split("\n")[0]})`
+		};
+	}
+	out = out.split("\n").map((l) => /^-{3,}\s*$/.test(l) ? "***" : l).join("\n").replace(/\n+$/, "");
+	const why = sameMeaning(masked.text, out, masked.nonce);
+	if (why) return {
+		body: asWritten,
+		reason: why
+	};
+	const restored = unmask(out, masked);
+	if (restored === null) return {
+		body: asWritten,
+		reason: "a protected block could not be put back"
+	};
+	return {
+		body: trimLines(restored.split("\n")).join("\n"),
+		reason: null
+	};
+}
+/** The engine's view of a deck, for the before/after check: slides, stacking, frontmatter. */
+function shape(pieces) {
+	const out = [];
+	pieces.forEach((p, i) => {
+		let fm = {};
+		try {
+			fm = p.frontmatter ? YAML.parse(p.frontmatter.yaml) ?? {} : {};
+		} catch {
+			fm = "invalid";
+		}
+		const keys = fm && typeof fm === "object" ? Object.keys(fm).length : 1;
+		if (!isSlide(p, i, keys)) return;
+		out.push([
+			i === 0 ? "head" : p.vertical ? "v" : "h",
+			p.frontmatter?.kind ?? null,
+			fm
+		]);
+	});
+	return JSON.stringify(out);
+}
+/**
+* Format a deck's text. `prettier` is Prettier itself (or anything with its `format`). Throws a
+* `DeckFormatError` when the result would not be the same deck — which the checks make a bug
+* report, never a silent change.
+*/
+async function formatDeck(source, prettier, options = {}) {
+	const bom = source.startsWith(BOM) ? BOM : "";
+	const text = (bom ? source.slice(1) : source).replace(/\r\n?/g, "\n");
+	const pieces = cutDeck(text);
+	const kept = [];
+	const parts = [];
+	let slide = 0;
+	for (const [i, piece] of pieces.entries()) {
+		let keys = 0;
+		try {
+			const v = piece.frontmatter ? YAML.parse(piece.frontmatter.yaml) : null;
+			keys = v && typeof v === "object" ? Object.keys(v).length : 0;
+		} catch {
+			keys = 1;
+		}
+		const counts = isSlide(piece, i, keys);
+		if (!counts && !(i === 0 && piece.frontmatter)) continue;
+		const report = (reason) => kept.push({
+			slide,
+			line: piece.line + 1,
+			reason
+		});
+		const lines = [];
+		if (piece.frontmatter) {
+			const fm = await formatYaml(piece.frontmatter.yaml, piece.frontmatter.kind, prettier, options);
+			if (fm.reason) report(fm.reason);
+			const yaml = fm.yaml ? fm.yaml.split("\n") : [];
+			if (piece.frontmatter.kind === "fence") lines.push(i === 0 ? "---" : piece.vertical ? "----" : "---", ...yaml, "---");
+			else lines.push(piece.vertical ? "----" : "---", "", piece.frontmatter.open.trim(), ...yaml, piece.frontmatter.close.trim());
+		} else if (i > 0) lines.push(piece.vertical ? "----" : "---");
+		const body = await formatBody(piece.body.join("\n"), prettier, options);
+		if (body.reason) report(`the body is left as written: ${body.reason}`);
+		if (body.body) {
+			if (lines.length) lines.push("");
+			lines.push(...body.body.split("\n"));
+		}
+		parts.push(lines.join("\n"));
+		if (counts) slide++;
+	}
+	const out = `${bom}${parts.join("\n\n")}\n`;
+	if (shape(pieces) !== shape(cutDeck(out.slice(bom.length)))) throw new DeckFormatError("Formatting would change the deck's slides or their frontmatter, so nothing was changed. Please report this deck at https://github.com/kadalcc/deck/issues.");
+	return {
+		text: out,
+		changed: out !== source,
+		kept
+	};
+}
+//#endregion
+export { DeckFormatError, formatDeck };

package/dist/guard.js

@@ -0,0 +1,68 @@
+import { placeholderPattern } from "./protect.js";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+//#region src/guard.ts
+const commonmark = unified().use(remarkParse).use(remarkGfm).use(remarkMath);
+const mdx = unified().use(remarkParse).use(remarkMdx).use(remarkGfm).use(remarkMath);
+/** Any value without the positions (and parser data) nested in it: JSX attributes carry both. */
+function bare(v) {
+	if (Array.isArray(v)) return v.map(bare);
+	if (!v || typeof v !== "object") return v;
+	return Object.fromEntries(Object.entries(v).filter(([k]) => k !== "position" && k !== "data").map(([k, x]) => [k, bare(x)]));
+}
+/** A tree as plain data: no positions, whitespace folded in text and HTML. */
+function plain(node) {
+	const out = {};
+	for (const [k, v] of Object.entries(node)) {
+		if (k === "position" || k === "data") continue;
+		if (k === "children") continue;
+		if (k === "value" && typeof v === "string" && (node.type === "text" || node.type === "html")) out[k] = v.replace(/\s+/g, " ").trim();
+		else out[k] = bare(v);
+	}
+	if (node.children) {
+		const kids = [];
+		for (const c of node.children) {
+			const p = plain(c);
+			const last = kids[kids.length - 1];
+			if (p.type === "text" && last?.type === "text") last.value = `${last.value ?? ""} ${p.value ?? ""}`.replace(/\s+/g, " ").trim();
+			else kids.push(p);
+		}
+		out.children = kids;
+	}
+	return out;
+}
+function parse(processor, text) {
+	try {
+		return JSON.stringify(plain(processor.parse(text)));
+	} catch {
+		return null;
+	}
+}
+/** Placeholders as MDX comment expressions on lines of their own (blank lines around). */
+function forMdx(text, nonce) {
+	const re = placeholderPattern(nonce);
+	return text.split("\n").map((line) => {
+		const m = re.exec(line);
+		return m ? `\n${m[1]}{/* kadal ${m[2]} */}\n` : line;
+	}).join("\n");
+}
+/**
+* Whether `after` says what `before` says (both masked with the same nonce). Returns null when it
+* does, or the reason it does not.
+*/
+function sameMeaning(before, after, nonce) {
+	const a = parse(commonmark, before);
+	const b = parse(commonmark, after);
+	if (a === null || b === null || a !== b) return "the Markdown would read differently";
+	const am = parse(mdx, forMdx(before, nonce));
+	if (am === null) return null;
+	const bm = parse(mdx, forMdx(after, nonce));
+	if (bm === null) return "the formatted MDX would not compile";
+	if (am !== bm) return "the MDX would read differently";
+	return null;
+}
+//#endregion
+export { sameMeaning };

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+import { DeckFormatError, DeckFormatOptions, FormatResult, PrettierLike, SlideReport, formatDeck } from "./format.js";
+import { Piece, cutDeck } from "./split.js";
+import { Plugin, SupportOptions } from "prettier";
+//#region src/index.d.ts
+export declare const languages: Plugin["languages"];
+export declare const options: SupportOptions;
+export declare const parsers: Plugin["parsers"];
+export declare const printers: Plugin["printers"];
+declare const plugin: Plugin;
+//#endregion
+export { DeckFormatError, type DeckFormatOptions, type FormatResult, type Piece, type PrettierLike, type SlideReport, cutDeck, plugin as default, formatDeck };

package/dist/index.js

@@ -0,0 +1,50 @@
+import { cutDeck } from "./split.js";
+import { DeckFormatError, formatDeck } from "./format.js";
+import * as prettier from "prettier";
+import { utils } from "prettier/doc";
+//#region src/index.ts
+const PARSER = "kadal-deck";
+const languages = [{
+	name: "Kadal Deck",
+	parsers: [PARSER],
+	filenames: ["deck.mdx", "slides.mdx"],
+	vscodeLanguageIds: ["kadal-deck"]
+}];
+const options = { kadalDeckBodies: {
+	type: "boolean",
+	category: "Kadal Deck",
+	default: true,
+	description: "Format each slide's Markdown too. false: only the separators and the frontmatter."
+} };
+const parser = {
+	astFormat: PARSER,
+	async parse(text, opts) {
+		const o = opts;
+		return {
+			type: "kadal-deck",
+			text: (await formatDeck(text, prettier, {
+				printWidth: o.printWidth,
+				tabWidth: o.tabWidth,
+				useTabs: o.useTabs,
+				proseWrap: o.proseWrap,
+				singleQuote: o.singleQuote,
+				bracketSpacing: o.bracketSpacing,
+				bodies: o.kadalDeckBodies !== false
+			})).text,
+			source: text
+		};
+	},
+	locStart: () => 0,
+	locEnd: (node) => node.source.length
+};
+const parsers = { [PARSER]: parser };
+const printer = { print: (path) => utils.replaceEndOfLine(path.node.text) };
+const printers = { [PARSER]: printer };
+const plugin = {
+	languages,
+	options,
+	parsers,
+	printers
+};
+//#endregion
+export { DeckFormatError, cutDeck, plugin as default, formatDeck, languages, options, parsers, printers };

package/dist/protect.js

@@ -0,0 +1,92 @@
+//#region src/protect.ts
+const FENCE = /^(\s*)(`{3,}|~{3,})/;
+const SINGLE_LINE = [
+	/^::[a-z][\w-]*::[ \t]*$/,
+	/^[ \t]*:{2,}code-group\b/,
+	/^[ \t]*:{2,}[ \t]*$/,
+	/^[ \t]*<<<[ \t]+\S/
+];
+/** The line index that ends a multi-line protected block starting at `i`, or null if `i` starts none. */
+function blockEnd(lines, i) {
+	const line = lines[i];
+	const fence = FENCE.exec(line);
+	if (fence) {
+		const mark = fence[2];
+		for (let k = i + 1; k < lines.length; k++) {
+			const close = /^\s*(`{3,}|~{3,})/.exec(lines[k]);
+			if (close && close[1][0] === mark[0] && close[1].length >= mark.length) return k;
+		}
+		return lines.length - 1;
+	}
+	const until = (closing, from = i) => {
+		for (let k = from; k < lines.length; k++) if (closing.test(lines[k])) return k;
+		return lines.length - 1;
+	};
+	const t = line.trimStart();
+	if (t.startsWith("$$")) {
+		if (/\$\$\s*$/.test(t.slice(2))) return i;
+		return until(/^\s*\$\$\s*$/, i + 1);
+	}
+	if (/^<Notes(\s|>|$)/.test(t)) return until(/<\/Notes>/);
+	if (/^<style(\s|>|$)/i.test(t)) return until(/<\/style\s*>/i);
+	if (t.startsWith("<!--")) return until(/-->/);
+	if (SINGLE_LINE.some((re) => re.test(line))) return i;
+	return null;
+}
+/** Swap every protected block for a placeholder line. */
+function mask(body, nonce) {
+	const lines = body.split("\n");
+	const out = [];
+	const segments = [];
+	for (let i = 0; i < lines.length; i++) {
+		const end = blockEnd(lines, i);
+		if (end === null) {
+			out.push(lines[i]);
+			continue;
+		}
+		const indent = /^[ \t]*/.exec(lines[i])[0];
+		segments.push({
+			lines: lines.slice(i, end + 1),
+			indent
+		});
+		out.push(`${indent}<!--kadal-fmt-${nonce}-${segments.length - 1}-->`);
+		i = end;
+	}
+	return {
+		text: out.join("\n"),
+		segments,
+		nonce
+	};
+}
+/** The placeholder lines' pattern for one nonce. */
+function placeholderPattern(nonce) {
+	return new RegExp(`^([ \\t]*)<!--kadal-fmt-${nonce}-(\\d+)-->[ \\t]*$`);
+}
+/**
+* Put the protected blocks back, re-indented with their placeholder. Null when a placeholder went
+* missing, appeared twice, or ended up inside a line — then the caller keeps the original.
+*/
+function unmask(text, masked) {
+	const re = placeholderPattern(masked.nonce);
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const line of text.split("\n")) {
+		const m = re.exec(line);
+		if (!m) {
+			if (line.includes(`<!--kadal-fmt-${masked.nonce}-`)) return null;
+			out.push(line);
+			continue;
+		}
+		const n = Number(m[2]);
+		const seg = masked.segments[n];
+		if (!seg || seen.has(n)) return null;
+		seen.add(n);
+		const indent = m[1];
+		for (const l of seg.lines) if (indent === seg.indent) out.push(l);
+		else if (l.startsWith(seg.indent)) out.push(indent + l.slice(seg.indent.length));
+		else out.push(l.trim() ? l : "");
+	}
+	return seen.size === masked.segments.length ? out.join("\n") : null;
+}
+//#endregion
+export { mask, placeholderPattern, unmask };

package/dist/split.d.ts

@@ -0,0 +1,26 @@
+//#region src/split.d.ts
+export interface PieceFrontmatter {
+  /** `---` fences (the separator opens it), or a ```yaml block as the body's first thing. */
+  kind: "fence" | "block";
+  /** The YAML between the fences, as written. */
+  yaml: string;
+  /** For a block: its opening and closing fence lines as written (```yaml … ```). */
+  open: string;
+  close: string;
+}
+export interface Piece {
+  /** The separator line as written; null for the piece at the top of the file. */
+  separator: string | null;
+  vertical: boolean;
+  frontmatter: PieceFrontmatter | null;
+  /** The body's lines (after the frontmatter, or the separator), as written. */
+  body: string[];
+  /** 0-based line where the piece starts in the text, for messages. */
+  line: number;
+}
+/**
+ * Cut the text at separators (the engine's `cut`, line for line). The head piece is always first,
+ * possibly empty.
+ */
+export declare function cutDeck(text: string): Piece[];
+//#endregion