@wdprlib/parser 3.2.0 → 4.0.0

package/src/parser/rules/block/embed-block/content.ts

@@ -0,0 +1,53 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../utils";
+import { isEmbedBlockName } from "./tags";
+
+export interface EmbedContentResult {
+  contents: string;
+  consumed: number;
+  foundClose: boolean;
+}
+
+export function collectEmbedContent(ctx: ParseContext, startPos: number): EmbedContentResult {
+  const contentParts: string[] = [];
+  let pos = startPos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token) break;
+
+    if (token.type === "BLOCK_END_OPEN") {
+      const closeNameResult = parseBlockName(ctx, pos + 1);
+      if (closeNameResult && isEmbedBlockName(closeNameResult.name.toLowerCase())) {
+        return { contents: contentParts.join(""), consumed, foundClose: true };
+      }
+    }
+
+    contentParts.push(token.value);
+    pos++;
+    consumed++;
+  }
+
+  return { contents: contentParts.join(""), consumed, foundClose: false };
+}
+
+export function consumeEmbedClose(ctx: ParseContext, startPos: number): number {
+  let pos = startPos + 1;
+  let consumed = 1;
+
+  const closeNameResult = parseBlockName(ctx, pos);
+  if (closeNameResult) {
+    pos += closeNameResult.consumed;
+    consumed += closeNameResult.consumed;
+  }
+  if (ctx.tokens[pos]?.type === "BLOCK_CLOSE") {
+    pos++;
+    consumed++;
+  }
+  if (ctx.tokens[pos]?.type === "NEWLINE") {
+    consumed++;
+  }
+
+  return consumed;
+}

package/src/parser/rules/block/embed-block/index.ts

@@ -0,0 +1,91 @@
+/**
+ *
+ * Block rule for Wikidot embed blocks: `[[embed]]`, `[[embedvideo]]`,
+ * and `[[embedaudio]]` (each with a matching closing tag).
+ *
+ * In original Wikidot, only HTML that matches a server-side allow-list is
+ * rendered. This parser does not perform that filtering -- the raw content
+ * between the tags is stored verbatim as an `embed-block` element. Validation
+ * and sanitisation are expected to happen at rendering time or on the server.
+ *
+ * The embed block is wrapped in a paragraph container in the AST, matching
+ * Wikidot's rendering behaviour where embeds sit inside `<p>` tags.
+ *
+ * If no closing tag is found, the rule fails to prevent consuming the rest
+ * of the document.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { collectEmbedContent, consumeEmbedClose } from "./content";
+import { parseEmbedBlockOpen } from "./open";
+
+/**
+ * Block rule for `[[embed]]`, `[[embedvideo]]`, and `[[embedaudio]]`.
+ *
+ * Content between the opening and closing tags is captured as raw text.
+ * The block name matching is case-insensitive; the closing tag may use
+ * any of the three names (`embed`, `embedvideo`, `embedaudio`) regardless
+ * of which was used to open.
+ */
+export const embedBlockRule: BlockRule = {
+  name: "embed-block",
+  startTokens: ["BLOCK_OPEN"],
+  requiresLineStart: false,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const openResult = parseEmbedBlockOpen(ctx, ctx.pos);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    let pos = openResult.pos;
+    let consumed = openResult.consumed;
+    const contentResult = collectEmbedContent(ctx, pos);
+    pos += contentResult.consumed;
+    consumed += contentResult.consumed;
+
+    if (!contentResult.foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: `Missing closing tag [[/${openResult.blockName}]] for [[${openResult.blockName}]]`,
+        position: openToken.position,
+      });
+      return { success: false };
+    }
+
+    const closeConsumed = consumeEmbedClose(ctx, pos);
+    pos += closeConsumed;
+    consumed += closeConsumed;
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "container",
+          data: {
+            type: "paragraph",
+            attributes: {},
+            elements: [
+              {
+                element: "embed-block",
+                data: {
+                  contents: contentResult.contents.trim(),
+                },
+              },
+            ],
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

package/src/parser/rules/block/embed-block/open.ts

@@ -0,0 +1,52 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../utils";
+import { isEmbedBlockName } from "./tags";
+
+export interface EmbedBlockOpenResult {
+  blockName: string;
+  pos: number;
+  consumed: number;
+}
+
+export function parseEmbedBlockOpen(
+  ctx: ParseContext,
+  startPos: number,
+): EmbedBlockOpenResult | null {
+  let pos = startPos;
+  let consumed = 0;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_OPEN") {
+    return null;
+  }
+  pos++;
+  consumed++;
+
+  const nameResult = parseBlockName(ctx, pos);
+  if (!nameResult) {
+    return null;
+  }
+
+  const blockName = nameResult.name.toLowerCase();
+  if (!isEmbedBlockName(blockName)) {
+    return null;
+  }
+  pos += nameResult.consumed;
+  consumed += nameResult.consumed;
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+  pos++;
+  consumed++;
+
+  return {
+    blockName,
+    pos,
+    consumed,
+  };
+}

package/src/parser/rules/block/embed-block/tags.ts

@@ -0,0 +1,5 @@
+const EMBED_BLOCK_NAMES = new Set(["embed", "embedvideo", "embedaudio"]);
+
+export function isEmbedBlockName(name: string): boolean {
+  return EMBED_BLOCK_NAMES.has(name);
+}

package/src/parser/rules/block/footnoteblock/attributes.ts

@@ -0,0 +1,73 @@
+import type { ParseContext } from "../../types";
+
+export interface FootnoteBlockAttributesResult {
+  attrs: Record<string, string>;
+  consumed: number;
+}
+
+/**
+ * Parses key/value attributes from tokens for `[[footnoteblock]]`.
+ *
+ * This is intentionally rule-local: the generic block attribute parser
+ * filters some names that this rule needs to preserve, notably `hide`.
+ */
+export function parseFootnoteBlockAttributes(
+  ctx: ParseContext,
+  startPos: number,
+): FootnoteBlockAttributesResult {
+  const attrs: Record<string, string> = {};
+  let pos = startPos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (
+      !token ||
+      token.type === "BLOCK_CLOSE" ||
+      token.type === "NEWLINE" ||
+      token.type === "EOF"
+    ) {
+      break;
+    }
+
+    if (token.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+      continue;
+    }
+
+    if (token.type === "TEXT" || token.type === "IDENTIFIER") {
+      const name = token.value.toLowerCase();
+      pos++;
+      consumed++;
+
+      const eqToken = ctx.tokens[pos];
+      if (eqToken?.type === "EQUALS") {
+        pos++;
+        consumed++;
+
+        const valueToken = ctx.tokens[pos];
+        if (valueToken?.type === "QUOTED_STRING") {
+          attrs[name] = stripQuotes(valueToken.value);
+          pos++;
+          consumed++;
+        } else if (valueToken?.type === "TEXT" || valueToken?.type === "IDENTIFIER") {
+          attrs[name] = valueToken.value;
+          pos++;
+          consumed++;
+        }
+      } else {
+        attrs[name] = "true";
+      }
+    } else {
+      pos++;
+      consumed++;
+    }
+  }
+
+  return { attrs, consumed };
+}
+
+function stripQuotes(value: string): string {
+  return value.startsWith('"') && value.endsWith('"') ? value.slice(1, -1) : value;
+}

package/src/parser/rules/block/footnoteblock/index.ts

@@ -0,0 +1,82 @@
+/**
+ *
+ * Block rule for the Wikidot footnote block: `[[footnoteblock]]`.
+ *
+ * This self-closing block tag marks the location in the page where all
+ * collected footnotes (from `[[footnote]]...[[/footnote]]` inline markers)
+ * should be rendered. It is analogous to a "footnotes section" placeholder.
+ *
+ * Optional attributes:
+ * - `title` -- custom heading text for the footnotes section.
+ * - `hide`  -- when `"true"` or `"yes"`, suppresses footnote rendering.
+ *
+ * Wikidot only honours the FIRST `[[footnoteblock]]` in a document;
+ * subsequent occurrences are treated as plain text. The parser tracks
+ * this via `ctx.scope.footnoteBlockParsed`, but note: that flag is per
+ * spread copy of `ParseContext` (see {@link ScopeContext.footnoteBlockParsed}).
+ * In practice the duplicate-rejection only fires for two top-level
+ * `[[footnoteblock]]` tokens; siblings inside the same body or across
+ * nested bodies both succeed today. The auto-append decision in
+ * `Parser.parse` uses a post-parse AST walk, so it is unaffected.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { parseFootnoteBlockOpen } from "./open";
+
+/**
+ * Block rule for `[[footnoteblock]]`.
+ *
+ * Parsing strategy:
+ * 1. Match BLOCK_OPEN + name "footnoteblock" (case-insensitive).
+ * 2. Parse optional attributes (`title`, `hide`) with the rule-local parser.
+ * 3. Consume closing `]]`.
+ * 4. If `ctx.scope.footnoteBlockParsed` is already `true` on the current
+ *    `ParseContext` copy, fail. Because `parseBlocksUntil` spreads a
+ *    fresh `ctx` per sibling rule, this only rejects a second
+ *    `[[footnoteblock]]` that arrives via the parser's top-level
+ *    dispatch loop in practice. See {@link ScopeContext.footnoteBlockParsed}.
+ * 5. Replace `ctx.scope` with the flag set to `true` and emit a `footnote-block`
+ *    element.
+ */
+export const footnoteBlockRule: BlockRule = {
+  name: "footnoteBlock",
+  startTokens: ["BLOCK_OPEN"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const openResult = parseFootnoteBlockOpen(ctx, ctx.pos);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    if (ctx.scope.footnoteBlockParsed) {
+      return { success: false };
+    }
+    ctx.scope = { ...ctx.scope, footnoteBlockParsed: true };
+
+    const title = openResult.attrs.title !== undefined ? openResult.attrs.title : null;
+    const hide = openResult.attrs.hide === "true" || openResult.attrs.hide === "yes";
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "footnote-block",
+          data: {
+            title,
+            hide,
+          },
+        },
+      ],
+      consumed: openResult.consumed,
+    };
+  },
+};

package/src/parser/rules/block/footnoteblock/open.ts

@@ -0,0 +1,53 @@
+import type { ParseContext } from "../../types";
+import { parseFootnoteBlockAttributes } from "./attributes";
+
+export interface FootnoteBlockOpenResult {
+  attrs: Record<string, string>;
+  consumed: number;
+}
+
+export function parseFootnoteBlockOpen(
+  ctx: ParseContext,
+  startPos: number,
+): FootnoteBlockOpenResult | null {
+  if (ctx.tokens[startPos]?.type !== "BLOCK_OPEN") {
+    return null;
+  }
+
+  let pos = startPos + 1;
+  let consumed = 1;
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  const nameToken = ctx.tokens[pos];
+  if (!nameToken || (nameToken.type !== "TEXT" && nameToken.type !== "IDENTIFIER")) {
+    return null;
+  }
+
+  if (nameToken.value.toLowerCase() !== "footnoteblock") {
+    return null;
+  }
+  pos++;
+  consumed++;
+
+  const attrResult = parseFootnoteBlockAttributes(ctx, pos);
+  pos += attrResult.consumed;
+  consumed += attrResult.consumed;
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  return {
+    attrs: attrResult.attrs,
+    consumed: consumed + 1,
+  };
+}

package/src/parser/rules/block/heading/index.ts

@@ -0,0 +1,87 @@
+/**
+ *
+ * Block rule for Wikidot headings: `+ Heading` through `++++++ Heading`.
+ *
+ * Headings are written with one to six `+` characters at the start of a
+ * line, followed by mandatory whitespace and then inline content:
+ *
+ * ```
+ * + H1 heading
+ * ++ H2 heading
+ * +++ H3 heading
+ * ```
+ *
+ * An optional `*` immediately after the `+` markers hides the heading
+ * from the table of contents:
+ *
+ * ```
+ * +* Hidden H1
+ * ```
+ *
+ * Seven or more `+` characters are NOT valid headings in Wikidot and
+ * the rule will fail, letting them fall through to paragraph parsing.
+ *
+ * Non-hidden headings are registered in `ctx.tocEntries` for later use
+ * by the table-of-contents module.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { parseInlineUntil } from "../../inline/utils";
+import { parseHeadingOpen } from "./open";
+import { extractHeadingText } from "./toc-text";
+
+/**
+ * Block rule for Wikidot headings (`+ ` through `++++++ `).
+ *
+ * Produces a container element with `type: { header: { level, "has-toc" } }`.
+ * The heading text is parsed for inline markup (bold, links, etc.).
+ */
+export const headingRule: BlockRule = {
+  name: "heading",
+  startTokens: ["HEADING_MARKER"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openResult = parseHeadingOpen(ctx);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    // Parse inline content until newline
+    let pos = openResult.bodyStart;
+    let consumed = openResult.consumed;
+    const inlineCtx: ParseContext = { ...ctx, pos };
+    const inlineResult = parseInlineUntil(inlineCtx, "NEWLINE");
+    const children: Element[] = inlineResult.elements;
+    consumed += inlineResult.consumed;
+    pos += inlineResult.consumed;
+
+    // Consume newline
+    if (ctx.tokens[pos]?.type === "NEWLINE") {
+      consumed++;
+    }
+
+    // Store TOC entry (only non-hidden headings)
+    if (!openResult.hidden) {
+      const headingText = extractHeadingText(children);
+      ctx.tocEntries.push({ level: openResult.level, text: headingText });
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "container",
+          data: {
+            type: { header: { level: openResult.level, "has-toc": !openResult.hidden } },
+            attributes: {},
+            elements: children,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

package/src/parser/rules/block/heading/open.ts

@@ -0,0 +1,50 @@
+import type { HeadingLevel } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+
+export interface HeadingOpenResult {
+  level: HeadingLevel;
+  hidden: boolean;
+  bodyStart: number;
+  consumed: number;
+}
+
+export function parseHeadingOpen(ctx: ParseContext): HeadingOpenResult | null {
+  const marker = ctx.tokens[ctx.pos];
+  if (marker?.type !== "HEADING_MARKER" || !marker.lineStart) {
+    return null;
+  }
+
+  if (!isHeadingLevel(marker.value.length)) {
+    return null;
+  }
+
+  let pos = ctx.pos + 1;
+  let consumed = 1;
+  let hidden = false;
+
+  if (ctx.tokens[pos]?.type === "STAR") {
+    hidden = true;
+    pos++;
+    consumed++;
+  }
+
+  if (ctx.tokens[pos]?.type !== "WHITESPACE") {
+    return null;
+  }
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  return {
+    level: marker.value.length,
+    hidden,
+    bodyStart: pos,
+    consumed,
+  };
+}
+
+function isHeadingLevel(length: number): length is HeadingLevel {
+  return length >= 1 && length <= 6;
+}

package/src/parser/rules/block/heading/toc-text.ts

@@ -0,0 +1,26 @@
+import type { Element } from "@wdprlib/ast";
+
+/**
+ * Recursively extracts plain text from heading children for TOC entries.
+ */
+export function extractHeadingText(elements: Element[]): string {
+  let text = "";
+  for (const el of elements) {
+    if (el.element === "text" && typeof el.data === "string") {
+      text += el.data;
+    } else if (hasNestedElements(el)) {
+      text += extractHeadingText(el.data.elements);
+    }
+  }
+  return text;
+}
+
+function hasNestedElements(el: Element): el is Extract<Element, { element: "container" }> {
+  return (
+    el.element === "container" &&
+    typeof el.data === "object" &&
+    el.data !== null &&
+    "elements" in el.data &&
+    Array.isArray(el.data.elements)
+  );
+}

package/src/parser/rules/block/{horizontal-rule.ts → horizontal-rule/index.ts}

@@ -14,8 +14,9 @@
  * @module
  */
 import type { Element } from "@wdprlib/ast";
-import type { BlockRule, ParseContext, RuleResult } from "../types";
-import { currentToken } from "../types";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { consumeHorizontalRuleLine } from "./syntax";
 
 /**
  * Block rule for horizontal rules (`----`).
@@ -34,28 +35,10 @@ export const horizontalRuleRule: BlockRule = {
       return { success: false };
     }
 
-    let pos = ctx.pos + 1;
-    let consumed = 1;
-
-    // Skip to end of line
-    while (pos < ctx.tokens.length) {
-      const token = ctx.tokens[pos];
-      if (!token || token.type === "NEWLINE" || token.type === "EOF") {
-        break;
-      }
-      pos++;
-      consumed++;
-    }
-
-    // Consume newline
-    if (ctx.tokens[pos]?.type === "NEWLINE") {
-      consumed++;
-    }
-
     return {
       success: true,
       elements: [{ element: "horizontal-rule" }],
-      consumed,
+      consumed: consumeHorizontalRuleLine(ctx),
     };
   },
 };

package/src/parser/rules/block/horizontal-rule/syntax.ts

@@ -0,0 +1,21 @@
+import type { ParseContext } from "../../types";
+
+export function consumeHorizontalRuleLine(ctx: ParseContext): number {
+  let pos = ctx.pos + 1;
+  let consumed = 1;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "NEWLINE" || token.type === "EOF") {
+      break;
+    }
+    pos++;
+    consumed++;
+  }
+
+  if (ctx.tokens[pos]?.type === "NEWLINE") {
+    consumed++;
+  }
+
+  return consumed;
+}