vantage-md 0.5.6 → 0.5.8

package/dist/index.cjs

@@ -42,10 +42,20 @@ let rehype_katex = require("rehype-katex");
 rehype_katex = __toESM(rehype_katex, 1);
 let rehype_slug = require("rehype-slug");
 rehype_slug = __toESM(rehype_slug, 1);
+let unist_util_visit = require("unist-util-visit");
 let yaml = require("yaml");
 yaml = __toESM(yaml, 1);
 let smol_toml = require("smol-toml");
 //#region src/rehypeSourceLines.ts
+/**
+* Tags that get a `data-source-line`.
+*
+* `td`/`th` are here for review mode: a comment anchors to the cell it was
+* written on, so the cell needs a line of its own to be found again. Every cell
+* in a row reports the *row's* start line — a GFM row is one source line — so a
+* line no longer names at most one anchorable element, and whatever resolves an
+* anchor has to break the tie by block hash (`useReviewHighlights`).
+*/
 const BLOCK_TAGS = /* @__PURE__ */ new Set([
 	"p",
 	"h1",
@@ -58,30 +68,153 @@ const BLOCK_TAGS = /* @__PURE__ */ new Set([
 	"blockquote",
 	"pre",
 	"table",
+	"td",
+	"th",
 	"tr",
 	"ul",
 	"ol",
 	"hr",
 	"div"
 ]);
-function visit(node, offset) {
+function visit$1(node, offset) {
 	if ("children" in node) {
 		for (const child of node.children) if (child.type === "element") {
 			if (BLOCK_TAGS.has(child.tagName) && child.position?.start?.line) {
 				child.properties = child.properties || {};
 				child.properties["dataSourceLine"] = child.position.start.line + offset;
 			}
-			visit(child, offset);
+			visit$1(child, offset);
 		}
 	}
 }
 const rehypeSourceLines = (options) => {
 	const offset = options?.offset ?? 0;
 	return (tree) => {
-		visit(tree, offset);
+		visit$1(tree, offset);
 	};
 };
 //#endregion
+//#region src/rehypeVantageAlerts.ts
+/**
+* GFM alerts — `> [!WARNING]` — compiled into `data-vantage-alert`.
+*
+* `remark-gfm` does not implement alerts, so until this plugin existed a
+* `> [!WARNING]` rendered as an ordinary blockquote with the literal marker
+* visible as its first words. Worse than merely unstyled: `@tailwindcss/typography`
+* italicises blockquotes and draws `open-quote`/`close-quote` around the first
+* paragraph, so a callout came out as an italic *quotation* whose opening words
+* were `"[!WARNING]`. That was the "Known gaps" entry in
+* `docs/reference/inline-markup.md` and OQ-10, filed rather than fixed, while
+* `styleGuide.ts` went on telling every agent to write them.
+*
+* The tokens are deliberately the ones the `tone` vocabulary already resolves —
+* an alert *is* the six-colour light/dark treatment `tone` shipped, which is
+* exactly what the gap entry said whoever fixed this should do rather than
+* building a second palette. `[!WARNING]` and `<!-- vantage: block tone=warning -->`
+* therefore agree by construction, and adding a theme still touches one
+* custom-property block.
+*
+* **This runs in the shared pipeline, so all four renderers get it** — the live
+* viewer, the package's exported viewer, the static export and the CLI checker's
+* `renderMarkdown`. That is what makes an injected title element acceptable here
+* where the collapse caret's glyph had to be drawn in CSS: the caret is injected
+* by app JS that may never run, and this is not (D5).
+*
+* ## What it does not do
+*
+* It does not touch a blockquote that carries no marker, and an unrecognised
+* marker (`[!HINT]`) is left exactly as it was — visible literal text, which is
+* the honest rendering of something GitHub also would not style. Silently
+* swallowing it would hide a typo that reads as a callout on neither renderer.
+*/
+/**
+* The five GFM alert kinds, lowercased.
+*
+* Deliberately *not* re-derived from `VANTAGE_TONES`: that list carries a sixth
+* token, `muted`, which is ours and is not an alert word. The overlap is the
+* point — the five that coincide share a palette — but the two vocabularies are
+* closed by different authorities and a change to one must not silently move the
+* other. A test asserts the five are a subset of the tones.
+*/
+const VANTAGE_ALERTS = [
+	"note",
+	"tip",
+	"important",
+	"warning",
+	"caution"
+];
+/** The visible label per kind. Title case, as GitHub renders it. */
+const ALERT_TITLES = {
+	note: "Note",
+	tip: "Tip",
+	important: "Important",
+	warning: "Warning",
+	caution: "Caution"
+};
+/**
+* The marker, anchored and requiring the rest of its line to be empty.
+*
+* GFM puts the marker alone on the blockquote's first line, and holding to that
+* is what keeps a paragraph that merely *begins* with bracketed text from being
+* eaten. The trailing newline is optional only for the degenerate blockquote
+* whose entire content is the marker.
+*
+* Measured against the real chain rather than assumed: `remark-parse` reads
+* `[!TIP]` as a shortcut link reference, and because no definition matches,
+* `mdast-util-to-hast` puts it back as **one** leading text node —
+* `"[!TIP]\nThe generalization: "` — not as a `[`/label/`]` triple. So a single
+* anchored test on the first text node is enough, and the plugin does not have
+* to reassemble the marker across siblings.
+*/
+const MARKER = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*(?:\r?\n|$)/;
+/** The first child, if it is an element. */
+function firstElement(node) {
+	const child = node.children.find((c) => c.type === "element" || c.type === "text" && c.value.trim() !== "");
+	return child?.type === "element" ? child : void 0;
+}
+/**
+* Compile `> [!KIND]` blockquotes into `data-vantage-alert="kind"`.
+*
+* Order in the chain matters twice, and both are stated in `pipeline.ts`:
+*
+* - **after `rehypeSourceLines`**, so the injected title carries no
+*   `data-source-line`. That is what keeps it out of `anchorBlockWithin`, which
+*   filters candidates to those with a finite line — otherwise a review comment
+*   on an alert would anchor to the word "Warning" instead of to the prose.
+* - **before `rehypeSanitize`**, so nothing reaches the DOM the schema has not
+*   passed. `dataVantageAlert` is allowlisted there by name *and* value, like
+*   every other `data-vantage-*` attribute.
+*/
+function rehypeVantageAlerts() {
+	return (tree) => {
+		(0, unist_util_visit.visit)(tree, "element", (node) => {
+			if (node.tagName !== "blockquote") return;
+			const paragraph = firstElement(node);
+			if (paragraph === void 0 || paragraph.tagName !== "p") return;
+			const lead = paragraph.children[0];
+			if (lead === void 0 || lead.type !== "text") return;
+			const match = MARKER.exec(lead.value);
+			if (match === null) return;
+			const kind = match[1].toLowerCase();
+			lead.value = lead.value.slice(match[0].length);
+			if (lead.value === "" && paragraph.children.length === 1) node.children = node.children.filter((c) => c !== paragraph);
+			node.properties = {
+				...node.properties,
+				dataVantageAlert: kind
+			};
+			node.children.unshift({
+				type: "element",
+				tagName: "div",
+				properties: { className: ["vantage-alert-title"] },
+				children: [{
+					type: "text",
+					value: ALERT_TITLES[kind]
+				}]
+			});
+		});
+	};
+}
+//#endregion
 //#region src/vantageDirectives.ts
 /**
 * The directive grammar and the closed vocabulary — one parser, no renderer.
@@ -894,6 +1027,7 @@ const sanitizeSchema = {
 			["dataVantageCollapseToggle", COLLAPSE_GROUP_ID],
 			["dataVantageRun", ...VANTAGE_RUNS],
 			["dataVantageOq", "true"],
+			["dataVantageAlert", ...VANTAGE_ALERTS],
 			"dataVantageLeaning"
 		],
 		code: [...rehype_sanitize.defaultSchema.attributes?.code || [], "className"],
@@ -939,6 +1073,7 @@ function buildRehypePlugins(options = {}) {
 	const { math = true, highlight = true, sourceLines = true, sanitize = true, bodyLineOffset = 0 } = options;
 	const plugins = [rehype_raw.default];
 	if (sourceLines) plugins.push([rehypeSourceLines, { offset: bodyLineOffset }]);
+	plugins.push(rehypeVantageAlerts);
 	plugins.push(rehypeVantageDirectives);
 	if (sanitize) plugins.push([rehype_sanitize.default, sanitizeSchema]);
 	plugins.push(rehype_slug.default);
@@ -1584,6 +1719,7 @@ The steps below predate the rewrite.
 - **Anything outside those sets is silently ignored** — nothing breaks, and nothing styles either. Run \`vantage-check\` on the document: the \`vantage/*\` rules are the only thing that will ever tell you a directive did nothing.
 - **Always close the comment with \`-->\`.** Never \`--!>\`, and never leave it open: Markdown reads every line below an unclosed \`<!--\` as part of the comment, and the whole rest of the document vanishes from the page. For the same reason \`-->\` cannot appear *inside* a value — it ends the comment early and spills the remainder into the page as literal text.
 - **In a list, indent the directive inside the item**, with blank lines around it (below). At the start of a line between two items it ends the list and starts a second one, which changes the numbering and the spacing in every renderer — the one thing a directive must never do.
+- **Every open question (\u{1F4AC}) with a stated leaning gets an \`oq\` directive.** The convention's prose — the emoji, the \`OQ-N\` id, the \`_Leaning:_\` line, the fill-in \`**Answer:**\` — produces no button on its own. Writing the convention and stopping there is the most common way this feature goes missing: the questions look complete, review mode is on, and there is nothing to click. **\`vantage-check\` reports it as an error** (\`vantage/oq-missing\`), because a question awaiting a ruling that the reviewer cannot file is not a style preference. Mark it \u{1F512} if it is blocked on something upstream and cannot be answered yet, or \u2705 once it is decided; either state needs no directive.
 - **A \`leaning\` restates the leaning; it is never "yes".** The one-click button in review mode files that text as a review comment, and the comment is all the agent reading it has — nobody remembers which button was clicked. \`leaning="Yes"\` beside a two-branch question is a support ticket.
 
 \`\`\`markdown
@@ -1601,12 +1737,14 @@ The steps below predate the rewrite.
   - Single dollars are **not** math delimiters: \`$HOME\` and \`$100\` stay literal, so prose and shell snippets are safe to write as-is.
 `;
 //#endregion
+exports.ALERT_TITLES = ALERT_TITLES;
 exports.DIRECTIVE_NAMES = DIRECTIVE_NAMES;
 exports.DIRECTIVE_VOCABULARY = DIRECTIVE_VOCABULARY;
 exports.DOC_STATUSES = DOC_STATUSES;
 exports.DOC_STATUS_TONES = DOC_STATUS_TONES;
 exports.SAFE_STYLE = SAFE_STYLE;
 exports.STYLE_GUIDE = STYLE_GUIDE;
+exports.VANTAGE_ALERTS = VANTAGE_ALERTS;
 exports.VANTAGE_BADGES = VANTAGE_BADGES;
 exports.VANTAGE_COLLAPSED = VANTAGE_COLLAPSED;
 exports.VANTAGE_EMPHASIS = VANTAGE_EMPHASIS;
@@ -1625,6 +1763,7 @@ exports.parseLineAnchor = parseLineAnchor;
 exports.parseVantageDirective = parseVantageDirective;
 exports.readVantageFrontmatter = readVantageFrontmatter;
 exports.rehypeSourceLines = rehypeSourceLines;
+exports.rehypeVantageAlerts = rehypeVantageAlerts;
 exports.rehypeVantageDirectives = rehypeVantageDirectives;
 exports.renderMarkdown = renderMarkdown;
 exports.renderMermaidBlocks = renderMermaidBlocks;