@wdprlib/parser 3.1.2 → 3.2.0

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

@@ -0,0 +1,238 @@
+/**
+ *
+ * Block rule for Wikidot-style blockquotes using `>` markers.
+ *
+ * Wikidot blockquotes are written with one or more `>` characters at the
+ * start of a line, followed by a mandatory space and then the content:
+ *
+ * ```
+ * > First level
+ * >> Second level
+ * > Back to first
+ * ```
+ *
+ * Key behaviours:
+ * - The depth is determined by the number of consecutive `>` characters.
+ * - A space after the `>` markers is required; lines like `>No space` are
+ *   consumed but silently discarded from output.
+ * - An empty line (just `> `) within the same depth acts as a paragraph
+ *   separator inside the blockquote.
+ * - Nesting is handled by the generic {@link processDepths} utility, which
+ *   converts flat depth-annotated rows into a recursive tree structure.
+ * - Maximum depth is capped at `MAX_BLOCKQUOTE_DEPTH` (30) to guard
+ *   against pathological input.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+import { parseInlineUntil } from "../inline/utils";
+import { processDepths, type DepthList } from "../../depth";
+
+/**
+ * Safety limit for blockquote nesting depth.
+ * Lines exceeding this depth are not parsed, preventing stack issues
+ * on deeply nested or malicious input.
+ */
+const MAX_BLOCKQUOTE_DEPTH = 30;
+
+/**
+ * Block rule for `>` prefix blockquotes.
+ *
+ * Parsing strategy:
+ * 1. Collect consecutive lines that begin with BLOCKQUOTE_MARKER at line start.
+ * 2. For each line, record the depth (number of `>` chars, zero-indexed)
+ *    and parse the inline content after the mandatory space.
+ * 3. Lines missing the required space are consumed but produce no output.
+ * 4. Feed the flat depth list into {@link processDepths} to build a nested tree.
+ * 5. Recursively convert the tree into nested blockquote container elements
+ *    via `buildBlockquoteElement()`.
+ */
+export const blockquoteRule: BlockRule = {
+  name: "blockquote",
+  startTokens: ["BLOCKQUOTE_MARKER"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const firstToken = currentToken(ctx);
+
+    if (!firstToken.lineStart) {
+      return { success: false };
+    }
+
+    // Collect depth-annotated lines
+    const depths: Array<{
+      depth: number;
+      ltype: null;
+      value: { elements: Element[]; hasLineBreak: boolean };
+    }> = [];
+    let pos = ctx.pos;
+    let consumed = 0;
+
+    while (pos < ctx.tokens.length) {
+      const markerToken = ctx.tokens[pos];
+      if (!markerToken || !markerToken.lineStart || markerToken.type !== "BLOCKQUOTE_MARKER") {
+        break;
+      }
+
+      // Depth is determined by the number of > characters
+      // Token value is like ">", ">>", ">>>", etc.
+      const depth = markerToken.value.length;
+
+      // Check maximum depth to prevent DOS
+      if (depth > MAX_BLOCKQUOTE_DEPTH) {
+        break;
+      }
+
+      // Skip marker
+      pos++;
+      consumed++;
+
+      // Wikidot requires a space after > markers
+      // Lines without space (e.g. ">No") are consumed but not output
+      if (ctx.tokens[pos]?.type !== "WHITESPACE") {
+        // Consume rest of line silently
+        while (pos < ctx.tokens.length && ctx.tokens[pos]?.type !== "NEWLINE") {
+          pos++;
+          consumed++;
+        }
+        if (ctx.tokens[pos]?.type === "NEWLINE") {
+          pos++;
+          consumed++;
+        }
+        continue;
+      }
+
+      // Skip whitespace after marker
+      while (ctx.tokens[pos]?.type === "WHITESPACE") {
+        pos++;
+        consumed++;
+      }
+
+      // Parse inline content until newline or paragraph break
+      const inlineCtx: ParseContext = { ...ctx, pos };
+      const inlineResult = parseInlineUntil(inlineCtx, "NEWLINE");
+      const inlineChildren: Element[] = inlineResult.elements;
+      consumed += inlineResult.consumed;
+      pos += inlineResult.consumed;
+
+      // Check if there's a line break
+      let hasLineBreak = false;
+      if (ctx.tokens[pos]?.type === "NEWLINE") {
+        hasLineBreak = true;
+        pos++;
+        consumed++;
+      }
+
+      // Append depth item (depth is 0-indexed, so subtract 1)
+      depths.push({
+        depth: depth - 1,
+        ltype: null,
+        value: { elements: inlineChildren, hasLineBreak },
+      });
+    }
+
+    // No rows parsed
+    if (depths.length === 0) {
+      // If we consumed tokens (e.g. lines without space after >), return empty success
+      if (consumed > 0) {
+        return { success: true, elements: [], consumed };
+      }
+      return { success: false };
+    }
+
+    // Process depths to build nested structure
+    const depthTrees = processDepths<null, { elements: Element[]; hasLineBreak: boolean }>(
+      null,
+      depths,
+    );
+
+    // Convert depth trees to blockquote elements
+    const blockquotes = depthTrees.map(({ list }) => buildBlockquoteElement(list));
+
+    // Return first blockquote (should usually be only one)
+    if (blockquotes.length === 0) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: blockquotes,
+      consumed,
+    };
+  },
+};
+
+/**
+ * Recursively converts a depth-tree (produced by `processDepths()`) into
+ * a blockquote container element.
+ *
+ * Leaf items are accumulated into paragraph containers. An empty-content
+ * item acts as a paragraph separator. When a nested sub-list is encountered,
+ * the current paragraph is flushed and a child blockquote is created.
+ *
+ * @param list - The depth list to convert.
+ * @returns A container element with `type: "blockquote"`.
+ */
+function buildBlockquoteElement(
+  list: DepthList<null, { elements: Element[]; hasLineBreak: boolean }>,
+): Element {
+  const children: Element[] = [];
+  let currentParagraphChildren: Element[] = [];
+
+  function flushParagraph() {
+    if (currentParagraphChildren.length > 0) {
+      // Remove trailing line break from paragraph
+      while (
+        currentParagraphChildren.length > 0 &&
+        currentParagraphChildren[currentParagraphChildren.length - 1]?.element === "line-break"
+      ) {
+        currentParagraphChildren.pop();
+      }
+      if (currentParagraphChildren.length > 0) {
+        children.push({
+          element: "container",
+          data: {
+            type: "paragraph",
+            attributes: {},
+            elements: currentParagraphChildren,
+          },
+        });
+      }
+      currentParagraphChildren = [];
+    }
+  }
+
+  for (const item of list) {
+    if (item.kind === "item") {
+      // Empty content line (e.g. "> ") acts as paragraph separator
+      if (item.value.elements.length === 0) {
+        flushParagraph();
+        continue;
+      }
+      // Add elements to current paragraph
+      currentParagraphChildren.push(...item.value.elements);
+      // Add line break after this line
+      if (item.value.hasLineBreak) {
+        currentParagraphChildren.push({ element: "line-break" });
+      }
+    } else {
+      // Nested blockquote - flush current paragraph and add nested blockquote
+      flushParagraph();
+      children.push(buildBlockquoteElement(item.children));
+    }
+  }
+
+  // Flush remaining paragraph content
+  flushParagraph();
+
+  return {
+    element: "container",
+    data: {
+      type: "blockquote",
+      attributes: {},
+      elements: children,
+    },
+  };
+}

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

@@ -0,0 +1,87 @@
+/**
+ *
+ * Block rule for Wikidot single-line center alignment: `= text`.
+ *
+ * When a line begins with a single `=` followed by whitespace, the rest
+ * of the line is rendered as a centered paragraph (`<p style="text-align: center;">`).
+ *
+ * This is distinct from the `[[=]]...[[/=]]` alignment container (handled
+ * by `align.ts`), which wraps multiple block-level elements. The center
+ * rule here only affects a single line.
+ *
+ * Conditions for the rule to match:
+ * - Token must be EQUALS at the start of a line.
+ * - Must be exactly one `=` (4+ consecutive equals are a content separator,
+ *   handled by `content-separator.ts`).
+ * - Must be followed by a WHITESPACE token.
+ *
+ * The inline content is parsed until the end of line.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+import { parseInlineUntil } from "../inline/utils";
+
+/**
+ * Block rule for single-line center alignment (`= text`).
+ *
+ * Produces a paragraph container with `style: "text-align: center;"`.
+ */
+export const centerRule: BlockRule = {
+  name: "center",
+  startTokens: ["EQUALS"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const marker = currentToken(ctx);
+
+    if (!marker.lineStart) {
+      return { success: false };
+    }
+
+    // Wikidot requires whitespace after = for center alignment
+    let pos = ctx.pos + 1;
+    let consumed = 1;
+
+    if (ctx.tokens[pos]?.type !== "WHITESPACE") {
+      return { success: false };
+    }
+
+    // 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++;
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "container",
+          data: {
+            type: "paragraph",
+            attributes: {
+              style: "text-align: center;",
+            },
+            elements: children,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

package/src/parser/rules/block/clear-float.ts

@@ -0,0 +1,75 @@
+/**
+ *
+ * Block rule for Wikidot's float-clearing syntax: `~~~~`.
+ *
+ * Four or more tilde characters (`~`) at the start of a line produce a
+ * `<div style="clear: both;">` (or left/right) element. This is commonly
+ * used after floated images or divs to prevent subsequent content from
+ * wrapping alongside them.
+ *
+ * Variants:
+ * - `~~~~` (or more tildes) -- `clear: both`
+ * - `~~~~<` -- `clear: left`
+ * - `~~~~>` -- `clear: right`
+ *
+ * Three tildes (`~~~`) do NOT trigger this rule in Wikidot -- the minimum
+ * is four. The tilde count is validated at parse time even though the
+ * lexer already tokenises valid sequences, as a defensive check.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+
+/**
+ * Block rule for the clear-float directive (`~~~~`, `~~~~<`, `~~~~>`).
+ *
+ * Produces a `clear-float` element whose data is the direction string:
+ * `"both"`, `"left"`, or `"right"`.
+ */
+export const clearFloatRule: BlockRule = {
+  name: "clear-float",
+  startTokens: ["CLEAR_FLOAT", "CLEAR_FLOAT_LEFT", "CLEAR_FLOAT_RIGHT"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const token = currentToken(ctx);
+
+    if (!token.lineStart) {
+      return { success: false };
+    }
+
+    // Count tildes - Wikidot requires at least 4
+    const tildeCount = token.value.replace(/[<>]$/, "").length;
+    if (tildeCount < 4) {
+      return { success: false };
+    }
+
+    // Determine direction
+    let direction: "both" | "left" | "right" = "both";
+    if (token.type === "CLEAR_FLOAT_LEFT") {
+      direction = "left";
+    } else if (token.type === "CLEAR_FLOAT_RIGHT") {
+      direction = "right";
+    }
+
+    let consumed = 1;
+
+    // Consume newline if present
+    if (ctx.tokens[ctx.pos + 1]?.type === "NEWLINE") {
+      consumed++;
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "clear-float",
+          data: direction,
+        },
+      ],
+      consumed,
+    };
+  },
+};

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

@@ -0,0 +1,187 @@
+/**
+ *
+ * Block rule for the Wikidot code block: `[[code]]...[[/code]]`.
+ *
+ * A code block captures its body as raw text (no inline parsing) and
+ * supports two optional attributes:
+ * - `type` -- the programming language for syntax highlighting (e.g.
+ *   `type="python"`).
+ * - `name` -- a label or filename displayed alongside the code.
+ *
+ * The content between the tags is collected verbatim, with a single
+ * trailing newline stripped. The parsed block is also pushed into
+ * `ctx.codeBlocks` so higher-level consumers can enumerate all code
+ * blocks in the document.
+ *
+ * Edge case: when a quoted attribute value swallows the `]]` and even
+ * the `[[/code]]` (e.g. `[[code type="css]][[/code]]`), the parser
+ * detects this by inspecting the QUOTED_STRING token and truncates the
+ * value at the first `]]`. If `[[/code]]` is also inside the quoted
+ * string, the body is treated as empty.
+ *
+ * @module
+ */
+import type { Element, CodeBlockData } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+import { parseBlockName } from "../utils";
+import { parseAttributesRaw } from "./utils";
+
+/**
+ * Block rule for `[[code type="..." name="..."]]...[[/code]]`.
+ *
+ * Body content is stored as-is (not parsed for inline markup). The rule
+ * also registers the code block in `ctx.codeBlocks` for document-level
+ * introspection.
+ */
+export const codeBlockRule: BlockRule = {
+  name: "code",
+  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 };
+    }
+
+    if (nameResult.name !== "code") {
+      return { success: false };
+    }
+
+    pos += nameResult.consumed;
+    consumed += nameResult.consumed;
+
+    // Parse attributes
+    const attrResult = parseAttributesRaw(ctx, pos);
+    pos += attrResult.consumed;
+    consumed += attrResult.consumed;
+
+    // Expect ]]
+    let closingSwallowed = false;
+    if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+      // Handle unclosed quoted string that swallowed ]]
+      // e.g. [[code type="css]][[/code]] → QUOTED_STRING consumed both ]] and [[/code]]
+      const prevToken = ctx.tokens[pos - 1];
+      if (prevToken?.type === "QUOTED_STRING" && prevToken.value.includes("]]")) {
+        const rawValue = prevToken.value;
+        const bracketIdx = rawValue.indexOf("]]");
+        const truncatedValue = rawValue.startsWith('"')
+          ? rawValue.slice(1, bracketIdx)
+          : rawValue.slice(0, bracketIdx);
+        // Update the attr that was assigned this malformed value
+        for (const key of Object.keys(attrResult.attrs)) {
+          const stored = attrResult.attrs[key]!;
+          if (
+            stored === rawValue ||
+            stored === rawValue.slice(1, -1) ||
+            stored === rawValue.slice(1)
+          ) {
+            attrResult.attrs[key] = truncatedValue;
+            break;
+          }
+        }
+        // If [[/code]] is also inside the quoted string, content is empty
+        if (rawValue.includes("[[/code]]")) {
+          closingSwallowed = true;
+        }
+      } else {
+        return { success: false };
+      }
+    } else {
+      pos++;
+      consumed++;
+    }
+
+    // Skip newline after opening tag if present
+    if (ctx.tokens[pos]?.type === "NEWLINE") {
+      pos++;
+      consumed++;
+    }
+
+    // Collect raw content until [[/code]]
+    let codeContent = "";
+    let foundClose = closingSwallowed;
+
+    while (!closingSwallowed && pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token || token.type === "EOF") {
+        break;
+      }
+
+      // Check for [[/code]]
+      if (token.type === "BLOCK_END_OPEN") {
+        const closeNameResult = parseBlockName(ctx, pos + 1);
+        if (closeNameResult && closeNameResult.name === "code") {
+          foundClose = true;
+          // Skip [[/code]]
+          pos++; // [[/
+          consumed++;
+          pos += closeNameResult.consumed; // code
+          consumed += closeNameResult.consumed;
+          // Skip ]]
+          if (ctx.tokens[pos]?.type === "BLOCK_CLOSE") {
+            pos++;
+            consumed++;
+          }
+          // Skip trailing newline
+          if (ctx.tokens[pos]?.type === "NEWLINE") {
+            pos++;
+            consumed++;
+          }
+          break;
+        }
+      }
+
+      // Collect raw content (don't parse)
+      codeContent += token.value;
+      pos++;
+      consumed++;
+    }
+
+    // Diagnostic for missing close tag
+    if (!foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: "Missing closing tag [[/code]] for [[code]]",
+        position: openToken.position,
+      });
+    }
+
+    // Trim trailing newline from content
+    codeContent = codeContent.replace(/\n$/, "");
+
+    // Store code block in context
+    const codeBlockData: CodeBlockData = {
+      contents: codeContent,
+      language: attrResult.attrs.type ?? null,
+      name: attrResult.attrs.name ?? null,
+    };
+    ctx.codeBlocks.push(codeBlockData);
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "code",
+          data: {
+            contents: codeContent,
+            language: attrResult.attrs.type ?? null,
+            name: attrResult.attrs.name ?? null,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};