@wdprlib/parser 3.1.2 → 4.0.0

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

@@ -0,0 +1,117 @@
+/**
+ * Block rule for Wikidot collapsible blocks: `[[collapsible]]...[[/collapsible]]`.
+ *
+ * A collapsible renders as a show/hide toggle with body content that can
+ * be expanded or collapsed. The opening tag accepts several attributes
+ * (which may span multiple lines):
+ *
+ * - `show`           -- label text for the "show" link (default: "+ show block").
+ * - `hide`           -- label text for the "hide" link (default: "- hide block").
+ * - `folded`         -- when `"no"`, the block starts in the expanded state.
+ * - `hideLocation`   -- where the toggle link appears: `"top"` (default),
+ *                       `"bottom"`, `"both"`, or `"neither"`/`"none"`.
+ *
+ * Key Wikidot-specific behaviours:
+ * - Collapsibles cannot nest. When the body parser encounters a second
+ *   `[[collapsible]]`, it is treated as plain text. This is achieved by
+ *   filtering the collapsible rule out of the block rule list for body parsing.
+ * - Orphaned `[[/collapsible]]` tags after the matched close are consumed and
+ *   emitted as `<br />` + literal text, matching Wikidot rendering.
+ * - An inline form (`[[collapsible]]text[[/collapsible]]` on one line) is
+ *   supported but uncommon.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { resolveToggleVisibility } from "./attributes";
+import { parseCollapsibleBody } from "./body";
+import { parseCollapsibleOpen } from "./open";
+import { consumeOrphanedCollapsibleCloses } from "./orphans";
+import { consumeCollapsibleCloseTag, isCollapsibleClose } from "./tags";
+
+/**
+ * Block rule for `[[collapsible ...]]...[[/collapsible]]`.
+ *
+ * Parsing strategy:
+ * 1. Match BLOCK_OPEN + name "collapsible".
+ * 2. Parse multiline attributes (show, hide, folded, hideLocation, etc.).
+ * 3. If a NEWLINE follows the opening tag, parse body as block content
+ *    with the collapsible rule itself excluded (to prevent nesting).
+ *    Otherwise, parse inline content until close tag or end of line
+ *    (inline form).
+ * 4. Consume the `[[/collapsible]]` closing tag.
+ * 5. Consume any orphaned `[[/collapsible]]` tags that follow, converting
+ *    them to `<br />` + literal text.
+ * 6. Derive `show-top` / `show-bottom` booleans from the `hideLocation`
+ *    attribute.
+ */
+export const collapsibleRule: BlockRule = {
+  name: "collapsible",
+  startTokens: ["BLOCK_OPEN"],
+  requiresLineStart: false,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const openResult = parseCollapsibleOpen(ctx);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    // Record opening tag position for diagnostics
+    const openPosition = openToken.position;
+
+    let pos = openResult.bodyStart;
+    let consumed = openResult.consumed;
+    const bodyResult = parseCollapsibleBody(ctx, pos, openResult.hasNewlineAfterOpen);
+    consumed += bodyResult.consumed;
+    pos += bodyResult.consumed;
+
+    // Check for missing close tag
+    if (!isCollapsibleClose(ctx, pos)) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: "Missing closing tag [[/collapsible]] for [[collapsible]]",
+        position: openPosition,
+      });
+    }
+
+    // Consume [[/collapsible]]
+    if (isCollapsibleClose(ctx, pos)) {
+      const closeConsumed = consumeCollapsibleCloseTag(ctx, pos);
+      consumed += closeConsumed;
+      pos += closeConsumed;
+    }
+
+    const orphanedResult = consumeOrphanedCollapsibleCloses(ctx, pos);
+    consumed += orphanedResult.consumed;
+
+    const toggleVisibility = resolveToggleVisibility(openResult.attrs);
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "collapsible",
+          data: {
+            elements: bodyResult.elements,
+            attributes: {},
+            "start-open": openResult.attrs.folded === "no",
+            "show-text": openResult.attrs.show ?? null,
+            "hide-text": openResult.attrs.hide ?? null,
+            "show-top": toggleVisibility.showTop,
+            "show-bottom": toggleVisibility.showBottom,
+          },
+        },
+        ...orphanedResult.elements,
+      ],
+      consumed,
+    };
+  },
+};

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

@@ -0,0 +1,51 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../utils";
+import { parseMultilineAttributes, type CollapsibleAttributes } from "./attributes";
+
+export interface CollapsibleOpenResult {
+  attrs: CollapsibleAttributes;
+  bodyStart: number;
+  consumed: number;
+  hasNewlineAfterOpen: boolean;
+}
+
+export function parseCollapsibleOpen(ctx: ParseContext): CollapsibleOpenResult | null {
+  if (ctx.tokens[ctx.pos]?.type !== "BLOCK_OPEN") {
+    return null;
+  }
+
+  let pos = ctx.pos + 1;
+  let consumed = 1;
+
+  const nameResult = parseBlockName(ctx, pos);
+  if (!nameResult || nameResult.name !== "collapsible") {
+    return null;
+  }
+
+  pos += nameResult.consumed;
+  consumed += nameResult.consumed;
+
+  const attrResult = parseMultilineAttributes(ctx, pos);
+  pos += attrResult.consumed;
+  consumed += attrResult.consumed;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  pos++;
+  consumed++;
+
+  const hasNewlineAfterOpen = ctx.tokens[pos]?.type === "NEWLINE";
+  if (hasNewlineAfterOpen) {
+    pos++;
+    consumed++;
+  }
+
+  return {
+    attrs: attrResult.attrs,
+    bodyStart: pos,
+    consumed,
+    hasNewlineAfterOpen,
+  };
+}

package/src/parser/rules/block/collapsible/orphans.ts

@@ -0,0 +1,31 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { isCollapsibleClose } from "./tags";
+
+export function consumeOrphanedCollapsibleCloses(
+  ctx: ParseContext,
+  startPos: number,
+): { elements: Element[]; consumed: number } {
+  const elements: Element[] = [];
+  let pos = startPos;
+  let consumed = 0;
+
+  while (isCollapsibleClose(ctx, pos)) {
+    elements.push({ element: "line-break" });
+
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token || token.type === "NEWLINE" || token.type === "EOF") break;
+      elements.push({ element: "text", data: token.value });
+      consumed++;
+      pos++;
+    }
+
+    if (ctx.tokens[pos]?.type === "NEWLINE") {
+      consumed++;
+      pos++;
+    }
+  }
+
+  return { elements, consumed };
+}

package/src/parser/rules/block/collapsible/tags.ts

@@ -0,0 +1,17 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../utils";
+
+export function isCollapsibleClose(ctx: ParseContext, pos: number): boolean {
+  if (ctx.tokens[pos]?.type !== "BLOCK_END_OPEN") return false;
+  const nameResult = parseBlockName(ctx, pos + 1);
+  return nameResult?.name === "collapsible";
+}
+
+export function consumeCollapsibleCloseTag(ctx: ParseContext, pos: number): number {
+  let closeConsumed = 1;
+  const nameResult = parseBlockName(ctx, pos + 1);
+  if (nameResult) closeConsumed += nameResult.consumed;
+  if (ctx.tokens[pos + closeConsumed]?.type === "BLOCK_CLOSE") closeConsumed++;
+  if (ctx.tokens[pos + closeConsumed]?.type === "NEWLINE") closeConsumed++;
+  return closeConsumed;
+}

package/src/parser/rules/block/comment/consume.ts

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

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

@@ -0,0 +1,47 @@
+/**
+ *
+ * Block rule for Wikidot comments: `[!-- ... --]`.
+ *
+ * Comments may span multiple lines and are completely stripped from the
+ * rendered output. The parser consumes all tokens from COMMENT_OPEN
+ * (`[!--`) through the matching COMMENT_CLOSE (`--]`), inclusive, plus
+ * any trailing newline.
+ *
+ * If the closing `--]` is never found (unterminated comment), the rule
+ * fails and tokens are left for other rules to handle.
+ *
+ * This rule requires line start so that inline comments appearing mid-line
+ * are handled by a separate inline rule instead.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { consumeBlockComment } from "./consume";
+
+/**
+ * Block rule for line-start comments (`[!-- ... --]`).
+ *
+ * Returns an empty elements array on success -- comments produce no output.
+ */
+export const blockCommentRule: BlockRule = {
+  name: "blockComment",
+  startTokens: ["COMMENT_OPEN"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const result = consumeBlockComment(ctx);
+
+    // Unterminated comment — let the inline comment rule emit the diagnostic
+    // to avoid duplication when the paragraph fallback retries this token.
+    if (!result) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [],
+      consumed: result.consumed,
+    };
+  },
+};

package/src/parser/rules/block/content-separator/index.ts

@@ -0,0 +1,49 @@
+/**
+ *
+ * Block rule for the Wikidot content separator: `====` (four or more `=`
+ * signs at the start of a line).
+ *
+ * A content separator is a structural divider in Wikidot pages, distinct
+ * from a horizontal rule (`----`). It signals a semantic section boundary
+ * rather than a visual line.
+ *
+ * Conditions:
+ * - Must start at line start.
+ * - Requires at least four consecutive EQUALS tokens.
+ * - Must be followed by NEWLINE or EOF (no trailing text allowed).
+ *
+ * A single `=` followed by whitespace is the center-alignment rule, and
+ * two or three `=` signs are not special -- only four or more trigger this
+ * rule.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { parseContentSeparatorSyntax } from "./syntax";
+
+/**
+ * Block rule for the content separator (`====`).
+ *
+ * Produces a `content-separator` element with no data payload.
+ */
+export const contentSeparatorRule: BlockRule = {
+  name: "content-separator",
+  startTokens: ["EQUALS"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const syntax = parseContentSeparatorSyntax(ctx);
+    if (!syntax) return { success: false };
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "content-separator",
+        },
+      ],
+      consumed: syntax.consumed,
+    };
+  },
+};

package/src/parser/rules/block/content-separator/syntax.ts

@@ -0,0 +1,33 @@
+import type { ParseContext } from "../../types";
+
+export interface ContentSeparatorSyntax {
+  consumed: number;
+}
+
+export function parseContentSeparatorSyntax(ctx: ParseContext): ContentSeparatorSyntax | null {
+  const first = ctx.tokens[ctx.pos];
+  if (first?.type !== "EQUALS" || !first.lineStart) {
+    return null;
+  }
+
+  let pos = ctx.pos;
+  let equalsCount = 0;
+
+  while (ctx.tokens[pos]?.type === "EQUALS") {
+    equalsCount++;
+    pos++;
+  }
+
+  if (equalsCount < 4) {
+    return null;
+  }
+
+  const nextToken = ctx.tokens[pos];
+  if (nextToken && nextToken.type !== "NEWLINE" && nextToken.type !== "EOF") {
+    return null;
+  }
+
+  return {
+    consumed: equalsCount + (nextToken?.type === "NEWLINE" ? 1 : 0),
+  };
+}

package/src/parser/rules/block/definition-list/collect.ts

@@ -0,0 +1,40 @@
+import type { ParseContext } from "../../types";
+import { parseDefinitionItem, type ParsedDefinitionItem } from "./items";
+
+export interface DefinitionListParseResult {
+  items: ParsedDefinitionItem[];
+  consumed: number;
+}
+
+export function collectDefinitionItems(ctx: ParseContext): DefinitionListParseResult {
+  const items: ParsedDefinitionItem[] = [];
+  let pos = ctx.pos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") {
+      break;
+    }
+
+    if (token.type !== "COLON" || !token.lineStart) {
+      break;
+    }
+
+    const result = parseDefinitionItem(ctx, pos);
+    if (!result) {
+      break;
+    }
+
+    items.push(result.item);
+    pos += result.consumed;
+    consumed += result.consumed;
+
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+  }
+
+  return { items, consumed };
+}

package/src/parser/rules/block/definition-list/index.ts

@@ -0,0 +1,63 @@
+/**
+ *
+ * Block rule for Wikidot definition lists written with the `: key : value` syntax.
+ *
+ * Each item starts at the beginning of a line with a COLON, followed by
+ * mandatory whitespace, the key (term), a second COLON, and then the value
+ * (definition). Multiple consecutive items form a single `<dl>` block.
+ *
+ * ```
+ * : Apple : A fruit that grows on trees.
+ * : Banana : A yellow curved fruit.
+ * ```
+ *
+ * Key parsing details:
+ * - Whitespace after the first colon is required (`": key"` not `":key"`).
+ * - The key portion supports inline markup (bold, links, etc.).
+ * - The value continues until a double newline, a new definition entry, or
+ *   the end of the document.
+ * - A single newline within the value does NOT break the entry -- parsing
+ *   continues on the next line.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { collectDefinitionItems } from "./collect";
+import { toDefinitionListItems } from "./items";
+
+/**
+ * Block rule for Wikidot definition lists (`: key : value`).
+ *
+ * Parsing strategy:
+ * 1. Verify the first token is a line-start COLON.
+ * 2. Repeatedly call `parseDefinitionItem()` to collect entries.
+ * 3. Stop when the current token is no longer a line-start COLON (i.e.
+ *    the definition list block has ended).
+ * 4. Convert internal items into the AST {@link DefinitionListItem} format.
+ * 5. Emit a single `definition-list` element.
+ */
+export const definitionListRule: BlockRule = {
+  name: "definitionList",
+  startTokens: ["COLON"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const result = collectDefinitionItems(ctx);
+
+    if (result.items.length === 0) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "definition-list",
+          data: toDefinitionListItems(result.items),
+        },
+      ],
+      consumed: result.consumed,
+    };
+  },
+};

package/src/parser/rules/block/definition-list/item-key.ts

@@ -0,0 +1,95 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseInlineUntil } from "../../inline/utils";
+
+export interface DefinitionItemKeyResult {
+  keyString: string;
+  key: Element[];
+  consumed: number;
+}
+
+export function parseDefinitionItemKey(
+  ctx: ParseContext,
+  startPos: number,
+): DefinitionItemKeyResult | null {
+  let pos = startPos;
+  let consumed = 0;
+
+  const colonToken = ctx.tokens[pos];
+  if (!colonToken || colonToken.type !== "COLON" || !colonToken.lineStart) {
+    return null;
+  }
+  pos++;
+  consumed++;
+
+  const whitespaceAfterColon = ctx.tokens[pos];
+  if (!whitespaceAfterColon || whitespaceAfterColon.type !== "WHITESPACE") {
+    return null;
+  }
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  const keyTokens: string[] = [];
+  const key: Element[] = [];
+  let foundSecondColon = false;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "NEWLINE" || token.type === "EOF") {
+      break;
+    }
+    if (token.type === "COLON") {
+      foundSecondColon = true;
+      pos++;
+      consumed++;
+      break;
+    }
+
+    const inlineCtx: ParseContext = { ...ctx, pos };
+    const result = parseInlineUntil(inlineCtx, "COLON");
+    if (result.elements.length > 0) {
+      key.push(...result.elements);
+      for (let i = 0; i < result.consumed; i++) {
+        const t = ctx.tokens[pos + i];
+        if (t) keyTokens.push(t.value);
+      }
+      pos += result.consumed;
+      consumed += result.consumed;
+    } else {
+      keyTokens.push(token.value);
+      pos++;
+      consumed++;
+    }
+  }
+
+  if (!foundSecondColon) {
+    return null;
+  }
+
+  trimTrailingWhitespaceText(key);
+
+  return {
+    keyString: keyTokens.join("").trim(),
+    key,
+    consumed,
+  };
+}
+
+function trimTrailingWhitespaceText(nodes: Element[]): void {
+  while (nodes.length > 0) {
+    const lastNode = nodes[nodes.length - 1];
+    if (
+      lastNode &&
+      lastNode.element === "text" &&
+      typeof lastNode.data === "string" &&
+      lastNode.data.trim() === ""
+    ) {
+      nodes.pop();
+    } else {
+      break;
+    }
+  }
+}

package/src/parser/rules/block/definition-list/item-value.ts

@@ -0,0 +1,56 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseInlineUntil } from "../../inline/utils";
+
+export interface DefinitionItemValueResult {
+  value: Element[];
+  consumed: number;
+}
+
+export function parseDefinitionItemValue(
+  ctx: ParseContext,
+  startPos: number,
+): DefinitionItemValueResult {
+  const value: Element[] = [];
+  let pos = startPos;
+  let consumed = 0;
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") {
+      break;
+    }
+
+    if (token.type === "NEWLINE") {
+      const nextToken = ctx.tokens[pos + 1];
+      if (nextToken?.type === "COLON" && nextToken.lineStart) {
+        pos++;
+        consumed++;
+        break;
+      }
+      if (nextToken?.type === "NEWLINE" || !nextToken || nextToken.type === "EOF") {
+        pos++;
+        consumed++;
+        break;
+      }
+    }
+
+    const inlineCtx: ParseContext = { ...ctx, pos };
+    const result = parseInlineUntil(inlineCtx, "NEWLINE");
+    if (result.elements.length > 0) {
+      value.push(...result.elements);
+      pos += result.consumed;
+      consumed += result.consumed;
+    } else {
+      pos++;
+      consumed++;
+    }
+  }
+
+  return { value, consumed };
+}

package/src/parser/rules/block/definition-list/items.ts

@@ -0,0 +1,54 @@
+import type { DefinitionListItem, Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseDefinitionItemKey } from "./item-key";
+import { parseDefinitionItemValue } from "./item-value";
+
+/**
+ * Internal representation of one definition list item before conversion
+ * to the AST's DefinitionListItem format.
+ */
+export interface ParsedDefinitionItem {
+  /** Raw string of the key, used for `key_string` in the AST. */
+  keyString: string;
+  /** Parsed inline elements representing the key / term. */
+  key: Element[];
+  /** Parsed inline elements representing the value / definition. */
+  value: Element[];
+}
+
+/**
+ * Parses a single definition list entry of the form `: key : value`.
+ *
+ * The function expects `startPos` to point at a line-start COLON token.
+ * It consumes the first colon, mandatory whitespace, key tokens up to
+ * the second colon, then value tokens until a double newline, a new entry,
+ * or end of input.
+ */
+export function parseDefinitionItem(
+  ctx: ParseContext,
+  startPos: number,
+): { item: ParsedDefinitionItem; consumed: number } | null {
+  const keyResult = parseDefinitionItemKey(ctx, startPos);
+  if (!keyResult) {
+    return null;
+  }
+
+  const valueResult = parseDefinitionItemValue(ctx, startPos + keyResult.consumed);
+
+  return {
+    item: {
+      keyString: keyResult.keyString,
+      key: keyResult.key,
+      value: valueResult.value,
+    },
+    consumed: keyResult.consumed + valueResult.consumed,
+  };
+}
+
+export function toDefinitionListItems(items: ParsedDefinitionItem[]): DefinitionListItem[] {
+  return items.map((item) => ({
+    key_string: item.keyString,
+    key: item.key,
+    value: item.value,
+  }));
+}