@wdprlib/parser 3.1.2 → 4.0.0

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/index.ts

@@ -0,0 +1,44 @@
+/**
+ *
+ * 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";
+import { consumeHorizontalRuleLine } from "./syntax";
+
+/**
+ * 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 };
+    }
+
+    return {
+      success: true,
+      elements: [{ element: "horizontal-rule" }],
+      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;
+}

package/src/parser/rules/block/html/body.ts

@@ -0,0 +1,114 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../utils";
+
+export interface HtmlBodyResult {
+  contents: string;
+  consumed: number;
+  foundClose: boolean;
+}
+
+/**
+ * Scan forward from `from` to see whether a real `[[/html]]` close tag
+ * exists later in the token stream.
+ */
+export function lookaheadHasHtmlClose(ctx: ParseContext, from: number): boolean {
+  for (let i = from; i < ctx.tokens.length; i++) {
+    const token = ctx.tokens[i];
+    if (!token || token.type === "EOF") return false;
+    if (token.type !== "BLOCK_END_OPEN") continue;
+
+    const closeName = parseBlockName(ctx, i + 1);
+    if (closeName?.name.toLowerCase() !== "html") continue;
+
+    let closePos = i + 1 + closeName.consumed;
+    while (ctx.tokens[closePos]?.type === "WHITESPACE") closePos++;
+    if (ctx.tokens[closePos]?.type === "BLOCK_CLOSE") return true;
+  }
+  return false;
+}
+
+export function collectHtmlBody(
+  ctx: ParseContext,
+  startPos: number,
+  disabled: boolean,
+): HtmlBodyResult {
+  const hasCloseAhead = disabled && lookaheadHasHtmlClose(ctx, startPos);
+  const contentParts: string[] = [];
+  let pos = startPos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") break;
+
+    if (
+      disabled &&
+      !hasCloseAhead &&
+      token.type === "NEWLINE" &&
+      ctx.tokens[pos + 1]?.type === "NEWLINE"
+    ) {
+      break;
+    }
+
+    if (isHtmlCloseAt(ctx, pos)) {
+      return { contents: contentParts.join(""), consumed, foundClose: true };
+    }
+
+    if (!disabled) {
+      contentParts.push(token.value);
+    }
+    pos++;
+    consumed++;
+  }
+
+  return { contents: contentParts.join(""), consumed, foundClose: false };
+}
+
+export function consumeHtmlClose(ctx: ParseContext, startPos: number): number {
+  let pos = startPos;
+  let consumed = 0;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_END_OPEN") {
+    return 0;
+  }
+
+  pos++;
+  consumed++;
+
+  const closeNameResult = parseBlockName(ctx, pos);
+  if (closeNameResult) {
+    pos += closeNameResult.consumed;
+    consumed += closeNameResult.consumed;
+  }
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  if (ctx.tokens[pos]?.type === "BLOCK_CLOSE") {
+    pos++;
+    consumed++;
+  }
+
+  if (ctx.tokens[pos]?.type === "NEWLINE") {
+    consumed++;
+  }
+
+  return consumed;
+}
+
+function isHtmlCloseAt(ctx: ParseContext, pos: number): boolean {
+  if (ctx.tokens[pos]?.type !== "BLOCK_END_OPEN") {
+    return false;
+  }
+
+  const closeNameResult = parseBlockName(ctx, pos + 1);
+  if (closeNameResult?.name.toLowerCase() !== "html") {
+    return false;
+  }
+
+  let checkPos = pos + 1 + closeNameResult.consumed;
+  while (ctx.tokens[checkPos]?.type === "WHITESPACE") checkPos++;
+  return ctx.tokens[checkPos]?.type === "BLOCK_CLOSE";
+}

package/src/parser/rules/block/html/diagnostics.ts

@@ -0,0 +1,11 @@
+import type { Position } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+
+export function addHtmlDisabledDiagnostic(ctx: ParseContext, position: Position): void {
+  ctx.diagnostics.push({
+    severity: "info",
+    code: "html-block-disabled",
+    message: "[[html]] block ignored: disabled by settings",
+    position,
+  });
+}

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

@@ -0,0 +1,95 @@
+/**
+ *
+ * Block rule for the Wikidot HTML block: `[[html]]...[[/html]]`.
+ *
+ * An HTML block embeds raw HTML that Wikidot renders inside a sandboxed
+ * `<iframe>`. The content between the tags is captured verbatim (no inline
+ * parsing) and stored as an `html` element in the AST.
+ *
+ * Supported attributes on the opening tag:
+ * - `style` -- applied to the containing iframe. Other attributes are
+ *   parsed but only `style` is used by Wikidot's renderer.
+ *
+ * The raw content is also pushed into `ctx.htmlBlocks` for document-level
+ * enumeration.
+ *
+ * If no `[[/html]]` closing tag is found, the rule fails and the opening
+ * tag falls through to text rendering (matching Wikidot behaviour).
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { collectHtmlBody, consumeHtmlClose } from "./body";
+import { addHtmlDisabledDiagnostic } from "./diagnostics";
+import { parseHtmlOpen } from "./open";
+
+export { lookaheadHasHtmlClose } from "./body";
+
+/**
+ * Block rule for `[[html]]...[[/html]]`.
+ *
+ * Body content is stored as raw text. The optional `style` attribute is
+ * passed through to the AST element for iframe styling.
+ */
+export const htmlBlockRule: BlockRule = {
+  name: "html",
+  startTokens: ["BLOCK_OPEN"],
+  requiresLineStart: false,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const openResult = parseHtmlOpen(ctx, ctx.pos);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    const disabled = ctx.settings.allowHtmlBlocks === false;
+    const bodyStart = ctx.pos + openResult.consumed;
+    const bodyResult = collectHtmlBody(ctx, bodyStart, disabled);
+    let consumed = openResult.consumed + bodyResult.consumed;
+
+    if (!bodyResult.foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: "Missing closing tag [[/html]] for [[html]]",
+        position: openToken.position,
+      });
+      if (!disabled) {
+        return { success: false };
+      }
+      addHtmlDisabledDiagnostic(ctx, openToken.position);
+      return { success: true, elements: [], consumed };
+    }
+
+    consumed += consumeHtmlClose(ctx, bodyStart + bodyResult.consumed);
+
+    if (disabled) {
+      addHtmlDisabledDiagnostic(ctx, openToken.position);
+      return { success: true, elements: [], consumed };
+    }
+
+    const contents = bodyResult.contents.trim();
+    ctx.htmlBlocks.push(contents);
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "html",
+          data: {
+            contents,
+            ...(openResult.style && { style: openResult.style }),
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

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

@@ -0,0 +1,36 @@
+import type { ParseContext } from "../../types";
+import { parseAttributesRaw, parseBlockName } from "../utils";
+
+export interface HtmlOpenResult {
+  style: string | undefined;
+  consumed: number;
+}
+
+export function parseHtmlOpen(ctx: ParseContext, startPos: number): HtmlOpenResult | null {
+  if (ctx.tokens[startPos]?.type !== "BLOCK_OPEN") {
+    return null;
+  }
+
+  let pos = startPos + 1;
+  let consumed = 1;
+
+  const nameResult = parseBlockName(ctx, pos);
+  if (!nameResult || nameResult.name.toLowerCase() !== "html") {
+    return null;
+  }
+  pos += nameResult.consumed;
+  consumed += nameResult.consumed;
+
+  const attrResult = parseAttributesRaw(ctx, pos);
+  pos += attrResult.consumed;
+  consumed += attrResult.consumed;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  return {
+    style: attrResult.attrs.style,
+    consumed: consumed + 1,
+  };
+}