@wdprlib/parser 3.1.2 → 4.0.0

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

@@ -0,0 +1,127 @@
+/**
+ *
+ * Central registry for all block-level parser rules.
+ *
+ * This module imports every block rule, re-exports each one individually
+ * (for selective use), and assembles them into the ordered `blockRules`
+ * array that the main parser iterates through.
+ *
+ * Rule ordering matters: rules earlier in the array are tried first.
+ * Line-start-only rules (comments, headings, lists, etc.) are naturally
+ * filtered by the `requiresLineStart` flag, but among rules that share
+ * a start token (e.g. BLOCK_OPEN), position in this array determines
+ * priority. For example, `codeBlockRule` is tried before `collapsibleRule`
+ * because both start with BLOCK_OPEN but code blocks should be matched
+ * first.
+ *
+ * The paragraph rule is deliberately excluded from the array -- it serves
+ * as a fallback and is exported separately as `blockFallbackRule`.
+ *
+ * @module
+ */
+import type { BlockRule } from "../types";
+import { headingRule } from "./heading";
+import { horizontalRuleRule } from "./horizontal-rule";
+import { listRule } from "./list";
+import { blockListRule } from "./block-list";
+import { blockquoteRule } from "./blockquote";
+import { definitionListRule } from "./definition-list";
+import { paragraphRule } from "./paragraph";
+import { divRule } from "./div";
+import { codeBlockRule } from "./code";
+import { collapsibleRule } from "./collapsible";
+import { tableRule } from "./table";
+import { tableBlockRule } from "./table-block";
+import { moduleRule } from "./module";
+import { footnoteBlockRule } from "./footnoteblock";
+import { blockCommentRule } from "./comment";
+import { centerRule } from "./center";
+import { contentSeparatorRule } from "./content-separator";
+import { clearFloatRule } from "./clear-float";
+import { alignRule } from "./align";
+import { tabviewRule } from "./tabview";
+import { includeRule } from "./include";
+import { mathBlockRule } from "./math";
+import { htmlBlockRule } from "./html";
+import { embedBlockRule } from "./embed-block";
+import { iframeRule } from "./iframe";
+import { iftagsRule } from "./iftags";
+import { tocRule } from "./toc";
+import { orphanLiRule } from "./orphan-li";
+import { bibliographyRule } from "./bibliography";
+
+export { headingRule } from "./heading";
+export { horizontalRuleRule } from "./horizontal-rule";
+export { listRule } from "./list";
+export { blockListRule } from "./block-list";
+export { blockquoteRule } from "./blockquote";
+export { definitionListRule } from "./definition-list";
+export { paragraphRule } from "./paragraph";
+export { divRule } from "./div";
+export { codeBlockRule } from "./code";
+export { collapsibleRule } from "./collapsible";
+export { tableRule } from "./table";
+export { tableBlockRule } from "./table-block";
+export { moduleRule } from "./module";
+export { footnoteBlockRule } from "./footnoteblock";
+export { blockCommentRule } from "./comment";
+export { centerRule } from "./center";
+export { contentSeparatorRule } from "./content-separator";
+export { clearFloatRule } from "./clear-float";
+export { alignRule } from "./align";
+export { tabviewRule } from "./tabview";
+export { includeRule } from "./include";
+export { mathBlockRule } from "./math";
+export { htmlBlockRule } from "./html";
+export { embedBlockRule } from "./embed-block";
+export { iframeRule } from "./iframe";
+export { iftagsRule } from "./iftags";
+export { tocRule } from "./toc";
+export { orphanLiRule } from "./orphan-li";
+export { bibliographyRule } from "./bibliography";
+
+/**
+ * All block rules in priority order.
+ *
+ * The main parser tries each rule in sequence for the current token.
+ * Rules with `requiresLineStart: true` are only attempted when the token
+ * is at line start, so their position relative to non-line-start rules
+ * is less critical. Among rules that share the same `startTokens` entry,
+ * earlier position wins.
+ *
+ * The paragraph rule is intentionally absent -- it is used as a fallback
+ * when no other rule matches (see `blockFallbackRule`).
+ */
+export const blockRules: BlockRule[] = [
+  blockCommentRule,
+  clearFloatRule,
+  contentSeparatorRule,
+  centerRule,
+  headingRule,
+  horizontalRuleRule,
+  tableRule,
+  tableBlockRule,
+  listRule,
+  blockListRule,
+  orphanLiRule,
+  blockquoteRule,
+  definitionListRule,
+  codeBlockRule,
+  collapsibleRule,
+  tocRule,
+  footnoteBlockRule,
+  moduleRule,
+  alignRule,
+  tabviewRule,
+  includeRule,
+  mathBlockRule,
+  htmlBlockRule,
+  embedBlockRule,
+  iframeRule,
+  iftagsRule,
+  bibliographyRule,
+  divRule,
+  // paragraphRule is not included - used as fallback
+];
+
+export { paragraphRule as blockFallbackRule };

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

@@ -0,0 +1,73 @@
+/**
+ *
+ * Block rule for Wikidot marker-based lists (`* item`, `# item`).
+ *
+ * Wikidot lists use leading `*` (bullet) or `#` (numbered) markers at the
+ * start of a line. Nesting is achieved by prepending spaces:
+ *
+ * ```
+ * * Item 1
+ *  * Nested bullet
+ *  # Nested numbered
+ * * Item 2
+ * ```
+ *
+ * The depth of each item is determined by the number of leading spaces
+ * before the marker. Mixed bullet/numbered lists are supported: when the
+ * list type changes at the same depth, a new sub-list is created.
+ *
+ * The flat depth-annotated items are converted into a recursive tree by
+ * `processDepths()`, then transformed into nested `list` AST elements
+ * by `buildListElement()`.
+ *
+ * Maximum nesting depth is capped at `MAX_LIST_DEPTH` (20).
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { buildNativeListElements, collectNativeListLines } from "./native";
+
+/**
+ * Block rule for marker-based lists (`* ` bullet, `# ` numbered).
+ *
+ * Parsing strategy:
+ * 1. Verify the first token is LIST_BULLET or LIST_NUMBER at line start.
+ * 2. Collect consecutive list lines, recording each item's depth (number
+ *    of leading spaces), type (bullet/numbered), and inline content.
+ * 3. Feed the flat depth array into `processDepths()` with type
+ *    comparison, producing a nested tree.
+ * 4. Convert the tree into `list` AST elements via `buildListElement()`.
+ */
+export const listRule: BlockRule = {
+  name: "list",
+  startTokens: ["LIST_BULLET", "LIST_NUMBER"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const firstToken = currentToken(ctx);
+
+    if (!firstToken.lineStart) {
+      return { success: false };
+    }
+
+    // Wikidot: list must start with list marker directly (no leading whitespace)
+    if (firstToken.type !== "LIST_BULLET" && firstToken.type !== "LIST_NUMBER") {
+      return { success: false };
+    }
+
+    const nativeList = collectNativeListLines(ctx);
+
+    // No items parsed - rule fails
+    if (nativeList.lines.length === 0) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: buildNativeListElements(nativeList.lines),
+      consumed: nativeList.consumed,
+    };
+  },
+};

package/src/parser/rules/block/list/line.ts

@@ -0,0 +1,77 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseInlineUntil } from "../../inline/utils";
+
+/**
+ * Safety limit for list nesting depth.
+ * Items deeper than this are not parsed, preventing stack overflow on
+ * deeply nested or adversarial input.
+ */
+const MAX_LIST_DEPTH = 20;
+
+export type InternalListType = "bullet" | "numbered";
+
+export interface ParsedListLine {
+  depth: number;
+  ltype: InternalListType;
+  value: Element[];
+}
+
+export type ListLineParseResult =
+  | { kind: "parsed"; line: ParsedListLine; consumed: number }
+  | { kind: "stop" };
+
+export function parseNativeListLine(ctx: ParseContext, startPos: number): ListLineParseResult {
+  const firstToken = ctx.tokens[startPos];
+
+  if (!firstToken || !firstToken.lineStart) {
+    return { kind: "stop" };
+  }
+
+  let pos = startPos;
+  let consumed = 0;
+  let depth = 0;
+
+  if (firstToken.type === "WHITESPACE") {
+    depth = firstToken.value.length;
+    pos++;
+    consumed++;
+  }
+
+  const markerToken = ctx.tokens[pos];
+  if (!markerToken || (markerToken.type !== "LIST_BULLET" && markerToken.type !== "LIST_NUMBER")) {
+    return { kind: "stop" };
+  }
+
+  if (depth > MAX_LIST_DEPTH) {
+    return { kind: "stop" };
+  }
+
+  const ltype: InternalListType = markerToken.type === "LIST_BULLET" ? "bullet" : "numbered";
+  pos++;
+  consumed++;
+
+  if (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  const inlineCtx: ParseContext = { ...ctx, pos };
+  const inlineResult = parseInlineUntil(inlineCtx, "NEWLINE");
+  consumed += inlineResult.consumed;
+  pos += inlineResult.consumed;
+
+  if (ctx.tokens[pos]?.type === "NEWLINE") {
+    consumed++;
+  }
+
+  return {
+    kind: "parsed",
+    line: {
+      depth,
+      ltype,
+      value: inlineResult.elements,
+    },
+    consumed,
+  };
+}

package/src/parser/rules/block/list/native.ts

@@ -0,0 +1,89 @@
+import type { Element, ListData, ListItem, ListType } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { processDepths, type DepthList } from "../../../depth";
+import { parseNativeListLine, type InternalListType, type ParsedListLine } from "./line";
+
+/**
+ * Default list type used as the top-level placeholder in
+ * `processDepths()`. The actual type of each sub-list is determined
+ * by its first item's marker.
+ */
+const GENERIC_LIST_TYPE: InternalListType = "bullet";
+
+export interface ParsedNativeList {
+  lines: ParsedListLine[];
+  consumed: number;
+}
+
+export function collectNativeListLines(ctx: ParseContext): ParsedNativeList {
+  const lines: ParsedListLine[] = [];
+  let pos = ctx.pos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const result = parseNativeListLine(ctx, pos);
+    if (result.kind === "stop") break;
+
+    lines.push(result.line);
+    pos += result.consumed;
+    consumed += result.consumed;
+  }
+
+  return { lines, consumed };
+}
+
+export function buildNativeListElements(lines: ParsedListLine[]): Element[] {
+  const depthTrees = processDepths<InternalListType, Element[]>(
+    GENERIC_LIST_TYPE,
+    lines,
+    (a, b) => a === b,
+  );
+
+  return depthTrees.map(({ ltype, list }) => buildListElement(ltype, list));
+}
+
+/**
+ * Converts the internal list type enum to the AST's ListType.
+ */
+function toListType(ltype: InternalListType): ListType {
+  return ltype === "numbered" ? "numbered" : "bullet";
+}
+
+function buildListElement(
+  topLtype: InternalListType,
+  list: DepthList<InternalListType, Element[]>,
+): Element {
+  return {
+    element: "list",
+    data: buildListData(topLtype, list),
+  };
+}
+
+function buildListData(
+  topLtype: InternalListType,
+  list: DepthList<InternalListType, Element[]>,
+): ListData {
+  const items: ListItem[] = [];
+
+  for (const item of list) {
+    if (item.kind === "item") {
+      items.push({
+        "item-type": "elements",
+        attributes: {},
+        elements: item.value,
+      });
+    } else {
+      items.push({
+        "item-type": "sub-list",
+        element: "list",
+        data: buildListData(item.ltype, item.children),
+      });
+    }
+  }
+
+  return {
+    type: toListType(topLtype),
+    attributes: {},
+    items,
+  };
+}

package/src/parser/rules/block/math/content.ts

@@ -0,0 +1,54 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../utils";
+
+export interface MathContentResult {
+  latexSource: string;
+  consumed: number;
+  foundClose: boolean;
+}
+
+export function collectMathContent(ctx: ParseContext, startPos: number): MathContentResult {
+  let latexSource = "";
+  let pos = startPos;
+  let consumed = 0;
+  let foundClose = false;
+
+  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?.name === "math") {
+        foundClose = true;
+        break;
+      }
+    }
+
+    latexSource += token.type === "BACKSLASH_BREAK" ? "\\\n" : token.value;
+    pos++;
+    consumed++;
+  }
+
+  return { latexSource, consumed, foundClose };
+}
+
+export function consumeMathClose(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/math/index.ts

@@ -0,0 +1,106 @@
+/**
+ *
+ * Block rule for the Wikidot math block: `[[math name]]...[[/math]]`.
+ *
+ * A math block captures LaTeX source code between the tags and stores it
+ * as a `math` element in the AST. The content is not parsed for inline
+ * markup.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { parseBlockName } from "../utils";
+import { collectMathContent, consumeMathClose } from "./content";
+import { parseMathName } from "./name";
+
+/**
+ * Block rule for `[[math name]]...[[/math]]`.
+ *
+ * Content is captured as raw LaTeX source. BACKSLASH_BREAK tokens are
+ * restored to their original `\\\n` form for correct LaTeX rendering.
+ */
+export const mathBlockRule: BlockRule = {
+  name: "math",
+  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;
+
+    const nameResult = parseBlockName(ctx, pos);
+    if (!nameResult || nameResult.name !== "math") {
+      return { success: false };
+    }
+    pos += nameResult.consumed;
+    consumed += nameResult.consumed;
+
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    const mathName = parseMathName(ctx, pos);
+    pos += mathName.consumed;
+    consumed += mathName.consumed;
+
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    if (ctx.tokens[pos]?.type === "NEWLINE") {
+      pos++;
+      consumed++;
+    }
+
+    const contentResult = collectMathContent(ctx, pos);
+    const latexSource = contentResult.latexSource.trim();
+    consumed += contentResult.consumed;
+    pos += contentResult.consumed;
+
+    if (!contentResult.foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: "Missing closing tag [[/math]] for [[math]]",
+        position: openToken.position,
+      });
+    } else {
+      const closeConsumed = consumeMathClose(ctx, pos);
+      pos += closeConsumed;
+      consumed += closeConsumed;
+    }
+
+    if (!latexSource) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "math",
+          data: {
+            name: mathName.name,
+            "latex-source": latexSource,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

package/src/parser/rules/block/math/name.ts

@@ -0,0 +1,35 @@
+import type { ParseContext } from "../../types";
+
+export interface MathNameResult {
+  name: string | null;
+  consumed: number;
+}
+
+export function parseMathName(ctx: ParseContext, startPos: number): MathNameResult {
+  let pos = startPos;
+  let consumed = 0;
+  let name = "";
+
+  const first = ctx.tokens[pos];
+  if (first?.type !== "IDENTIFIER" && first?.type !== "TEXT") {
+    return { name: null, consumed: 0 };
+  }
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (
+      !token ||
+      token.type === "BLOCK_CLOSE" ||
+      token.type === "WHITESPACE" ||
+      token.type === "NEWLINE"
+    ) {
+      break;
+    }
+
+    name += token.value;
+    pos++;
+    consumed++;
+  }
+
+  return { name: name === "" ? null : name, consumed };
+}

package/src/parser/rules/block/module/backlinks/index.ts

@@ -0,0 +1,31 @@
+/**
+ *
+ * Parser rule for the Wikidot `[[module Backlinks]]` block.
+ *
+ * Displays pages that link to the current page (or a specified page).
+ * Accepts an optional `page` attribute to target a specific page.
+ *
+ * @module
+ */
+
+import type { ModuleRule } from "../types";
+import type { BacklinksModuleData } from "./types";
+
+/**
+ * Module rule for `[[module Backlinks]]`.
+ *
+ * Parses the optional `page` attribute. When not specified, the rendering
+ * application should show backlinks for the current page.
+ */
+export const backlinksModuleRule: ModuleRule = {
+  name: "module-backlinks",
+  acceptsNames: ["backlinks"],
+  hasBody: false,
+
+  parse(_ctx, _pos, args): BacklinksModuleData {
+    return {
+      module: "backlinks",
+      page: args.page ?? null,
+    };
+  },
+};

package/src/parser/rules/block/module/backlinks/types.ts

@@ -0,0 +1,21 @@
+/**
+ *
+ * Type definitions for the Backlinks module.
+ *
+ * The `[[module Backlinks]]` block displays a list of pages that link to
+ * the specified page (or the current page if no `page` attribute is given).
+ *
+ * @module
+ */
+
+/**
+ * AST data for a `[[module Backlinks]]` element.
+ *
+ * The rendering application should query for pages that contain links to
+ * the target page and display them as a list.
+ */
+export interface BacklinksModuleData {
+  module: "backlinks";
+  /** Target page for which to find backlinks, or null for the current page */
+  page: string | null;
+}