@wdprlib/parser 3.1.2 → 3.2.0

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

@@ -0,0 +1,153 @@
+/**
+ *
+ * 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 { parseBlockName } from "./utils";
+
+/**
+ * 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 };
+    }
+
+    let pos = ctx.pos + 1;
+    let consumed = 1;
+
+    // Parse block name
+    const nameResult = parseBlockName(ctx, pos);
+    if (!nameResult) {
+      return { success: false };
+    }
+
+    const blockName = nameResult.name.toLowerCase();
+    if (blockName !== "embed" && blockName !== "embedvideo" && blockName !== "embedaudio") {
+      return { success: false };
+    }
+    pos += nameResult.consumed;
+    consumed += nameResult.consumed;
+
+    // Skip whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Expect ]]
+    if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Collect content until [[/embed]], [[/embedvideo]], or [[/embedaudio]]
+    let contents = "";
+    let foundClose = false;
+
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token) break;
+
+      // Check for closing [[/embed*]]
+      if (token.type === "BLOCK_END_OPEN") {
+        const closeNameResult = parseBlockName(ctx, pos + 1);
+        if (closeNameResult) {
+          const closeName = closeNameResult.name.toLowerCase();
+          if (closeName === "embed" || closeName === "embedvideo" || closeName === "embedaudio") {
+            foundClose = true;
+            break;
+          }
+        }
+      }
+
+      contents += token.value;
+      pos++;
+      consumed++;
+    }
+
+    // Require closing tag - without it, fail to prevent consuming entire document
+    if (!foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: `Missing closing tag [[/${blockName}]] for [[${blockName}]]`,
+        position: openToken.position,
+      });
+      return { success: false };
+    }
+
+    // Consume [[/embed*]]
+    if (ctx.tokens[pos]?.type === "BLOCK_END_OPEN") {
+      pos++;
+      consumed++;
+      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") {
+        pos++;
+        consumed++;
+      }
+    }
+
+    // Trim the contents
+    contents = contents.trim();
+
+    // Wikidotと同じく、embed-blockをparagraphで囲む
+    return {
+      success: true,
+      elements: [
+        {
+          element: "container",
+          data: {
+            type: "paragraph",
+            attributes: {},
+            elements: [
+              {
+                element: "embed-block",
+                data: {
+                  contents,
+                },
+              },
+            ],
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

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

@@ -0,0 +1,200 @@
+/**
+ *
+ * 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";
+
+/**
+ * Parses key/value attributes from tokens (e.g. `title="Custom title"`).
+ *
+ * This is a local attribute parser specific to the footnoteblock rule.
+ * It handles TEXT or IDENTIFIER names, optional `=` with quoted or
+ * unquoted values, and boolean attributes (name without value).
+ *
+ * @param ctx      - Parse context.
+ * @param startPos - Token index to start scanning.
+ * @returns Parsed attribute map and the number of tokens consumed.
+ */
+function parseAttributes(
+  ctx: ParseContext,
+  startPos: number,
+): { attrs: Record<string, string>; consumed: number } {
+  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;
+    }
+
+    // Skip whitespace
+    if (token.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+      continue;
+    }
+
+    // Attribute name (TEXT or IDENTIFIER token)
+    if (token.type === "TEXT" || token.type === "IDENTIFIER") {
+      const name = token.value.toLowerCase();
+      pos++;
+      consumed++;
+
+      // Check for =
+      const eqToken = ctx.tokens[pos];
+      if (eqToken?.type === "EQUALS") {
+        pos++;
+        consumed++;
+
+        // Get value (quoted string or text)
+        const valueToken = ctx.tokens[pos];
+        if (valueToken?.type === "QUOTED_STRING") {
+          // Remove quotes
+          let value = valueToken.value;
+          if (value.startsWith('"') && value.endsWith('"')) {
+            value = value.slice(1, -1);
+          }
+          attrs[name] = value;
+          pos++;
+          consumed++;
+        } else if (valueToken?.type === "TEXT" || valueToken?.type === "IDENTIFIER") {
+          attrs[name] = valueToken.value;
+          pos++;
+          consumed++;
+        }
+      } else {
+        // Boolean attribute
+        attrs[name] = "true";
+      }
+    } else {
+      // Unknown token, skip
+      pos++;
+      consumed++;
+    }
+  }
+
+  return { attrs, consumed };
+}
+
+/**
+ * Block rule for `[[footnoteblock]]`.
+ *
+ * Parsing strategy:
+ * 1. Match BLOCK_OPEN + name "footnoteblock" (case-insensitive).
+ * 2. Parse optional attributes (`title`, `hide`).
+ * 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 };
+    }
+
+    let pos = ctx.pos + 1;
+    let consumed = 1;
+
+    // Skip whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Check for block name
+    const nameToken = ctx.tokens[pos];
+    if (!nameToken || (nameToken.type !== "TEXT" && nameToken.type !== "IDENTIFIER")) {
+      return { success: false };
+    }
+
+    const blockName = nameToken.value.toLowerCase();
+    if (blockName !== "footnoteblock") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Parse optional attributes (title="...")
+    const { attrs, consumed: attrConsumed } = parseAttributes(ctx, pos);
+    pos += attrConsumed;
+    consumed += attrConsumed;
+
+    // Expect ]]
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+    if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Reject a second `[[footnoteblock]]` that arrives on the same
+    // `ParseContext` copy (in practice: at the top level — siblings
+    // inside `parseBlocksUntil` each get a fresh spread). The flag
+    // lives in the immutable `scope` group, so the mutation is
+    // expressed as a scope replacement. The cross-scope duplicate-
+    // rejection is a separate, known limitation.
+    if (ctx.scope.footnoteBlockParsed) {
+      return { success: false };
+    }
+    ctx.scope = { ...ctx.scope, footnoteBlockParsed: true };
+
+    // Extract title and hide from attributes
+    const title = attrs.title !== undefined ? attrs.title : null;
+    const hide = attrs.hide === "true" || attrs.hide === "yes";
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "footnote-block",
+          data: {
+            title,
+            hide,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

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

@@ -0,0 +1,142 @@
+/**
+ *
+ * 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, HeadingLevel } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+import { parseInlineUntil } from "../inline/utils";
+
+/**
+ * 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 marker = currentToken(ctx);
+
+    if (!marker.lineStart) {
+      return { success: false };
+    }
+
+    // Wikidot requires whitespace after heading marker
+    // Check format: + (space)content OR +* (space)content
+    let pos = ctx.pos + 1;
+    let consumed = 1;
+    let hidden = false;
+
+    // Check for hidden marker (*) - must come immediately after + markers
+    if (ctx.tokens[pos]?.type === "STAR") {
+      hidden = true;
+      pos++;
+      consumed++;
+    }
+
+    // Whitespace is required after + or +*
+    if (ctx.tokens[pos]?.type !== "WHITESPACE") {
+      return { success: false };
+    }
+
+    // Wikidot only supports h1-h6 (1-6 plus signs). 7+ is not a heading.
+    if (marker.value.length > 6) {
+      return { success: false };
+    }
+    const depth = marker.value.length as 1 | 2 | 3 | 4 | 5 | 6;
+
+    // Skip whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Parse inline content until newline
+    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 (!hidden) {
+      const headingText = extractText(children);
+      ctx.tocEntries.push({ level: depth, text: headingText });
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "container",
+          data: {
+            type: { header: { level: depth as HeadingLevel, "has-toc": !hidden } },
+            attributes: {},
+            elements: children,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};
+
+/**
+ * Recursively extracts the plain-text content from a tree of elements.
+ *
+ * Used to build the `text` field for table-of-contents entries. Only
+ * `text` elements and containers with nested `elements` are traversed;
+ * other element types (images, etc.) are ignored.
+ *
+ * @param elements - The heading's inline child elements.
+ * @returns Concatenated plain text.
+ */
+function extractText(elements: Element[]): string {
+  let text = "";
+  for (const el of elements) {
+    if (el.element === "text" && typeof el.data === "string") {
+      text += el.data;
+    } else if (
+      el.element === "container" &&
+      el.data &&
+      typeof el.data === "object" &&
+      "elements" in el.data
+    ) {
+      text += extractText(el.data.elements as Element[]);
+    }
+  }
+  return text;
+}

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

@@ -0,0 +1,61 @@
+/**
+ *
+ * Block rule for Wikidot horizontal rules: `----` (four or more hyphens
+ * at the start of a line).
+ *
+ * The lexer emits an HR_MARKER token for sequences of four or more `-`
+ * characters at line start. This rule consumes the marker, any remaining
+ * tokens on the line, and an optional trailing newline, producing a single
+ * `horizontal-rule` element (rendered as `<hr />`).
+ *
+ * Any text after the `----` on the same line is silently discarded,
+ * matching Wikidot's behaviour.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+
+/**
+ * Block rule for horizontal rules (`----`).
+ *
+ * Produces a `horizontal-rule` element with no data payload.
+ */
+export const horizontalRuleRule: BlockRule = {
+  name: "horizontalRule",
+  startTokens: ["HR_MARKER"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const marker = currentToken(ctx);
+
+    if (!marker.lineStart) {
+      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,
+    };
+  },
+};