@wdprlib/parser 3.2.0 → 4.0.0

package/src/parser/rules/block/module/walk/map/stateful-list.ts

@@ -0,0 +1,40 @@
+import type { Element, ListItem } from "@wdprlib/ast";
+import { listElement } from "../children";
+import type { StatefulTransformResult } from "./types";
+
+export function mapListItemsWithState<S>(
+  items: ListItem[],
+  state: S,
+  transform: (elements: Element[], state: S) => StatefulTransformResult<S>,
+): { items: ListItem[]; state: S } {
+  const newItems: ListItem[] = [];
+  let currentState = state;
+
+  for (const item of items) {
+    if (item["item-type"] === "elements") {
+      const result = transform(item.elements, currentState);
+      newItems.push({
+        "item-type": "elements",
+        attributes: item.attributes,
+        elements: result.elements,
+      });
+      currentState = result.state;
+      continue;
+    }
+
+    const result = transform([listElement(item.data)], currentState);
+    const resolvedList = result.elements[0];
+    if (resolvedList?.element === "list") {
+      newItems.push({
+        "item-type": "sub-list",
+        element: "list",
+        data: resolvedList.data,
+      });
+    } else {
+      newItems.push(item);
+    }
+    currentState = result.state;
+  }
+
+  return { items: newItems, state: currentState };
+}

package/src/parser/rules/block/module/walk/map/stateful-table.ts

@@ -0,0 +1,23 @@
+import type { Element, TableCell, TableRow } from "@wdprlib/ast";
+import type { StatefulTransformResult } from "./types";
+
+export function mapTableRowsWithState<S>(
+  rows: TableRow[],
+  state: S,
+  transform: (elements: Element[], state: S) => StatefulTransformResult<S>,
+): { rows: TableRow[]; state: S } {
+  const newRows: TableRow[] = [];
+  let currentState = state;
+
+  for (const row of rows) {
+    const newCells: TableCell[] = [];
+    for (const cell of row.cells) {
+      const result = transform(cell.elements, currentState);
+      newCells.push({ ...cell, elements: result.elements });
+      currentState = result.state;
+    }
+    newRows.push({ ...row, cells: newCells });
+  }
+
+  return { rows: newRows, state: currentState };
+}

package/src/parser/rules/block/module/walk/map/stateful-tabs.ts

@@ -0,0 +1,19 @@
+import type { Element, TabData } from "@wdprlib/ast";
+import type { StatefulTransformResult } from "./types";
+
+export function mapTabsWithState<S>(
+  tabs: TabData[],
+  state: S,
+  transform: (elements: Element[], state: S) => StatefulTransformResult<S>,
+): { tabs: TabData[]; state: S } {
+  const newTabs: TabData[] = [];
+  let currentState = state;
+
+  for (const tab of tabs) {
+    const result = transform(tab.elements, currentState);
+    newTabs.push({ ...tab, elements: result.elements });
+    currentState = result.state;
+  }
+
+  return { tabs: newTabs, state: currentState };
+}

package/src/parser/rules/block/module/walk/map/stateful.ts

@@ -0,0 +1,71 @@
+import type { Element } from "@wdprlib/ast";
+import { getGenericElementChildren, withGenericElementChildren } from "../children";
+import { mapDefinitionListItemsWithState } from "./stateful-definition-list";
+import { mapListItemsWithState } from "./stateful-list";
+import { mapTableRowsWithState } from "./stateful-table";
+import { mapTabsWithState } from "./stateful-tabs";
+import type { StatefulTransformResult } from "./types";
+
+/**
+ * Create a new element with all child arrays transformed by a stateful function.
+ */
+export function mapElementChildrenWithState<S>(
+  element: Element,
+  state: S,
+  transform: (elements: Element[], state: S) => StatefulTransformResult<S>,
+): { element: Element; state: S } {
+  if (element.element === "list") {
+    const result = mapListItemsWithState(element.data.items, state, transform);
+    return {
+      element: {
+        element: "list",
+        data: { ...element.data, items: result.items },
+      },
+      state: result.state,
+    };
+  }
+
+  if (element.element === "table") {
+    const result = mapTableRowsWithState(element.data.rows, state, transform);
+    return {
+      element: {
+        element: "table",
+        data: { ...element.data, rows: result.rows },
+      },
+      state: result.state,
+    };
+  }
+
+  if (element.element === "definition-list") {
+    const result = mapDefinitionListItemsWithState(element.data, state, transform);
+    return {
+      element: {
+        element: "definition-list",
+        data: result.items,
+      },
+      state: result.state,
+    };
+  }
+
+  if (element.element === "tab-view") {
+    const result = mapTabsWithState(element.data, state, transform);
+    return {
+      element: {
+        element: "tab-view",
+        data: result.tabs,
+      },
+      state: result.state,
+    };
+  }
+
+  const children = getGenericElementChildren(element);
+  if (children === null) {
+    return { element, state };
+  }
+
+  const result = transform(children, state);
+  return {
+    element: withGenericElementChildren(element, result.elements),
+    state: result.state,
+  };
+}

package/src/parser/rules/block/module/walk/map/stateless-definition-list.ts

@@ -0,0 +1,12 @@
+import type { DefinitionListItem, Element } from "@wdprlib/ast";
+
+export function mapDefinitionListItems(
+  items: DefinitionListItem[],
+  transform: (elements: Element[]) => Element[],
+): DefinitionListItem[] {
+  return items.map((item) => ({
+    key_string: item.key_string,
+    key: transform(item.key),
+    value: transform(item.value),
+  }));
+}

package/src/parser/rules/block/module/walk/map/stateless-list.ts

@@ -0,0 +1,29 @@
+import type { Element, ListItem } from "@wdprlib/ast";
+import { listElement } from "../children";
+
+export function mapListItems(
+  items: ListItem[],
+  transform: (elements: Element[]) => Element[],
+): ListItem[] {
+  return items.map((item) => {
+    if (item["item-type"] === "elements") {
+      return {
+        "item-type": "elements",
+        attributes: item.attributes,
+        elements: transform(item.elements),
+      };
+    }
+
+    const subListResult = transform([listElement(item.data)]);
+    const resolvedList = subListResult[0];
+    if (resolvedList?.element !== "list") {
+      return item;
+    }
+
+    return {
+      "item-type": "sub-list",
+      element: "list",
+      data: resolvedList.data,
+    };
+  });
+}

package/src/parser/rules/block/module/walk/map/stateless-table.ts

@@ -0,0 +1,11 @@
+import type { Element, TableRow } from "@wdprlib/ast";
+
+export function mapTableRows(
+  rows: TableRow[],
+  transform: (elements: Element[]) => Element[],
+): TableRow[] {
+  return rows.map((row) => ({
+    ...row,
+    cells: row.cells.map((cell) => ({ ...cell, elements: transform(cell.elements) })),
+  }));
+}

package/src/parser/rules/block/module/walk/map/stateless-tabs.ts

@@ -0,0 +1,5 @@
+import type { Element, TabData } from "@wdprlib/ast";
+
+export function mapTabs(tabs: TabData[], transform: (elements: Element[]) => Element[]): TabData[] {
+  return tabs.map((tab) => ({ ...tab, elements: transform(tab.elements) }));
+}

package/src/parser/rules/block/module/walk/map/stateless.ts

@@ -0,0 +1,51 @@
+import type { Element } from "@wdprlib/ast";
+import { getGenericElementChildren, withGenericElementChildren } from "../children";
+import { mapDefinitionListItems } from "./stateless-definition-list";
+import { mapListItems } from "./stateless-list";
+import { mapTableRows } from "./stateless-table";
+import { mapTabs } from "./stateless-tabs";
+
+/**
+ * Create a new element with all child element arrays transformed by a function.
+ */
+export function mapElementChildren(
+  element: Element,
+  transform: (elements: Element[]) => Element[],
+): Element {
+  if (element.element === "list") {
+    return {
+      element: "list",
+      data: {
+        ...element.data,
+        items: mapListItems(element.data.items, transform),
+      },
+    };
+  }
+
+  if (element.element === "table") {
+    return {
+      element: "table",
+      data: {
+        ...element.data,
+        rows: mapTableRows(element.data.rows, transform),
+      },
+    };
+  }
+
+  if (element.element === "definition-list") {
+    return {
+      element: "definition-list",
+      data: mapDefinitionListItems(element.data, transform),
+    };
+  }
+
+  if (element.element === "tab-view") {
+    return {
+      element: "tab-view",
+      data: mapTabs(element.data, transform),
+    };
+  }
+
+  const children = getGenericElementChildren(element);
+  return children === null ? element : withGenericElementChildren(element, transform(children));
+}

package/src/parser/rules/block/module/walk/map/types.ts

@@ -0,0 +1,6 @@
+import type { Element } from "@wdprlib/ast";
+
+export interface StatefulTransformResult<S> {
+  elements: Element[];
+  state: S;
+}

package/src/parser/rules/block/module/walk/traverse.ts

@@ -0,0 +1,65 @@
+import type { Element } from "@wdprlib/ast";
+import { getGenericElementChildren, listElement } from "./children";
+
+/**
+ * Walk all elements recursively in depth-first order, calling a callback for each.
+ *
+ * The callback is invoked for every element in the tree, including elements nested
+ * inside lists, tables, definition lists, tab views, and any element with a
+ * `data.elements` array. The callback is called before descending into children
+ * (pre-order traversal).
+ *
+ * This is a read-only traversal; the callback cannot modify the tree structure.
+ * Use `mapElementChildren` or `mapElementChildrenWithState` for transformations.
+ *
+ * @param elements - Array of elements to traverse
+ * @param callback - Function called for each element encountered
+ */
+export function walkElements(elements: Element[], callback: (element: Element) => void): void {
+  for (const element of elements) {
+    callback(element);
+    walkElementChildren(element, callback);
+  }
+}
+
+function walkElementChildren(element: Element, callback: (element: Element) => void): void {
+  if (element.element === "list") {
+    for (const item of element.data.items) {
+      if (item["item-type"] === "elements") {
+        walkElements(item.elements, callback);
+      } else if (item["item-type"] === "sub-list") {
+        walkElements([listElement(item.data)], callback);
+      }
+    }
+    return;
+  }
+
+  if (element.element === "table") {
+    for (const row of element.data.rows) {
+      for (const cell of row.cells) {
+        walkElements(cell.elements, callback);
+      }
+    }
+    return;
+  }
+
+  if (element.element === "definition-list") {
+    for (const item of element.data) {
+      walkElements(item.key, callback);
+      walkElements(item.value, callback);
+    }
+    return;
+  }
+
+  if (element.element === "tab-view") {
+    for (const tab of element.data) {
+      walkElements(tab.elements, callback);
+    }
+    return;
+  }
+
+  const children = getGenericElementChildren(element);
+  if (children !== null) {
+    walkElements(children, callback);
+  }
+}

package/src/parser/rules/block/orphan-li/content.ts

@@ -0,0 +1,60 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { isLiClose } from "./tags";
+
+export interface OrphanLiContentResult {
+  elements: Element[];
+  consumed: number;
+  foundClose: boolean;
+}
+
+export function collectOrphanLiContent(ctx: ParseContext, startPos: number): OrphanLiContentResult {
+  const elements: Element[] = [
+    { element: "text", data: "[[" },
+    { element: "text", data: "li" },
+    { element: "text", data: "]]" },
+  ];
+  let pos = startPos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") {
+      break;
+    }
+
+    const liClose = isLiClose(ctx, pos);
+    if (liClose) {
+      elements.push({ element: "text", data: "[[/" });
+      elements.push({ element: "text", data: "li" });
+      elements.push({ element: "text", data: "]]" });
+      pos += liClose.consumed;
+      consumed += liClose.consumed;
+
+      if (ctx.tokens[pos]?.type === "NEWLINE") {
+        consumed++;
+      }
+
+      return { elements, consumed, foundClose: true };
+    }
+
+    if (token.type === "NEWLINE") {
+      elements.push({ element: "line-break" });
+      pos++;
+      consumed++;
+      continue;
+    }
+
+    if (token.type === "WHITESPACE" && token.lineStart) {
+      pos++;
+      consumed++;
+      continue;
+    }
+
+    elements.push({ element: "text", data: token.value });
+    pos++;
+    consumed++;
+  }
+
+  return { elements, consumed, foundClose: false };
+}

package/src/parser/rules/block/orphan-li/index.ts

@@ -0,0 +1,75 @@
+/**
+ *
+ * Block rule for `[[li]]...[[/li]]` appearing outside of any `[[ul]]`/`[[ol]]` block.
+ *
+ * When `[[li]]` is used without an enclosing list block, Wikidot does NOT
+ * create a list item. Instead, it treats the tags as literal text and
+ * renders the body content without `<p>` wrapping, using `<br />` for
+ * newlines.
+ *
+ * Example input:
+ * ```
+ * [[li]]
+ * Baz
+ * [[/li]]
+ * ```
+ *
+ * Rendered output:
+ * ```
+ * [[li]]<br />Baz<br />[[/li]]
+ * ```
+ *
+ * If no `[[/li]]` closing tag is found, the rule fails.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { collectOrphanLiContent } from "./content";
+import { parseOrphanLiOpen } from "./open";
+
+/**
+ * Block rule for orphaned `[[li]]...[[/li]]` (outside any list block).
+ *
+ * The opening and closing tags are emitted as literal text elements, and
+ * newlines within the body become `<br />` elements. Leading whitespace
+ * on each line is discarded.
+ */
+export const orphanLiRule: BlockRule = {
+  name: "orphan-li",
+  startTokens: ["BLOCK_OPEN"],
+  requiresLineStart: false,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const openResult = parseOrphanLiOpen(ctx);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    const contentResult = collectOrphanLiContent(ctx, openResult.bodyStart);
+    let consumed = openResult.consumed;
+    consumed += contentResult.consumed;
+
+    if (!contentResult.foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: "Missing closing tag [[/li]] for [[li]]",
+        position: openToken.position,
+      });
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: contentResult.elements,
+      consumed,
+    };
+  },
+};

package/src/parser/rules/block/orphan-li/open.ts

@@ -0,0 +1,25 @@
+import type { ParseContext } from "../../types";
+import { isLiOpen } from "./tags";
+
+export interface OrphanLiOpenResult {
+  bodyStart: number;
+  consumed: number;
+}
+
+export function parseOrphanLiOpen(ctx: ParseContext): OrphanLiOpenResult | null {
+  const liOpen = isLiOpen(ctx, ctx.pos);
+  if (!liOpen) {
+    return null;
+  }
+
+  const closePos = ctx.pos + liOpen.consumed;
+  if (ctx.tokens[closePos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  const consumed = liOpen.consumed + 1;
+  return {
+    bodyStart: ctx.pos + consumed,
+    consumed,
+  };
+}

package/src/parser/rules/block/orphan-li/tags.ts

@@ -0,0 +1,40 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../utils";
+
+export interface TagMatch {
+  consumed: number;
+}
+
+/**
+ * Tests whether the tokens at `pos` form a `[[li]]` opening tag.
+ * Only the exact name `"li"` matches; `[[li_]]` is not recognised.
+ */
+export function isLiOpen(ctx: ParseContext, pos: number): TagMatch | null {
+  if (ctx.tokens[pos]?.type !== "BLOCK_OPEN") return null;
+
+  const nameResult = parseBlockName(ctx, pos + 1);
+  if (nameResult?.name !== "li") {
+    return null;
+  }
+
+  return { consumed: 1 + nameResult.consumed };
+}
+
+/**
+ * Tests whether the tokens at `pos` form a `[[/li]]` closing tag.
+ */
+export function isLiClose(ctx: ParseContext, pos: number): TagMatch | null {
+  if (ctx.tokens[pos]?.type !== "BLOCK_END_OPEN") return null;
+
+  const nameResult = parseBlockName(ctx, pos + 1);
+  if (nameResult?.name !== "li") {
+    return null;
+  }
+
+  let consumed = 1 + nameResult.consumed;
+  if (ctx.tokens[pos + consumed]?.type === "BLOCK_CLOSE") {
+    consumed++;
+  }
+
+  return { consumed };
+}

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

@@ -0,0 +1,12 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseInlineUntil } from "../../inline/utils";
+
+export interface ParagraphContentResult {
+  elements: Element[];
+  consumed: number;
+}
+
+export function parseInlineContent(ctx: ParseContext): ParagraphContentResult {
+  return parseInlineUntil(ctx, "PARAGRAPH_BREAK");
+}

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

@@ -0,0 +1,60 @@
+/**
+ * Paragraph rule
+ *
+ * Collects inline content until paragraph break (double newline) or end of input.
+ * Line breaks within paragraphs are handled by the newlineLineBreakRule.
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { parseInlineContent } from "./content";
+import { normalizeParagraphElements } from "./normalize";
+
+/**
+ * Paragraph is the fallback block rule.
+ *
+ * Wikidot behavior:
+ * - Single newline -> <br> (handled by newlineLineBreakRule)
+ * - Blank line (double newline) -> new paragraph
+ */
+export const paragraphRule: BlockRule = {
+  name: "paragraph",
+  startTokens: [],
+  requiresLineStart: false,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const result = parseInlineContent(ctx);
+    if (result.elements.length === 0) {
+      return { success: false };
+    }
+
+    const elements = normalizeParagraphElements(result.elements);
+    if (elements.length === 0) {
+      return { success: false };
+    }
+
+    const nextPos = ctx.pos + result.consumed;
+    const nextToken = ctx.tokens[nextPos];
+    if (nextToken?.type === "COLON" && nextToken.lineStart) {
+      return {
+        success: true,
+        elements: [...elements, { element: "line-break" }],
+        consumed: result.consumed,
+      };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "container",
+          data: {
+            type: "paragraph",
+            attributes: {},
+            elements,
+          },
+        },
+      ],
+      consumed: result.consumed,
+    };
+  },
+};

package/src/parser/rules/block/paragraph/normalize.ts

@@ -0,0 +1,52 @@
+import type { Element } from "@wdprlib/ast";
+import { processCloseSpanMarkers } from "./span-markers";
+
+type PreservedLineBreak = Extract<Element, { element: "line-break" }> & {
+  _preservedTrailingBreak?: boolean;
+};
+
+export function normalizeParagraphElements(source: Element[]): Element[] {
+  let elements = processCloseSpanMarkers(source);
+
+  removeTrailingLineBreaks(elements);
+  removeTrailingWhitespaceText(elements);
+  elements = removeLeadingLineBreaks(elements);
+
+  return elements;
+}
+
+function removeTrailingLineBreaks(elements: Element[]): void {
+  while (elements.length > 0 && elements[elements.length - 1]?.element === "line-break") {
+    const lastEl = elements[elements.length - 1] as PreservedLineBreak;
+    if (lastEl._preservedTrailingBreak) {
+      delete lastEl._preservedTrailingBreak;
+      break;
+    }
+    elements.pop();
+  }
+}
+
+function removeTrailingWhitespaceText(elements: Element[]): void {
+  while (elements.length > 0) {
+    const last = elements[elements.length - 1];
+    if (
+      last?.element === "text" &&
+      "data" in last &&
+      typeof last.data === "string" &&
+      last.data.trim() === ""
+    ) {
+      elements.pop();
+    } else {
+      break;
+    }
+  }
+}
+
+function removeLeadingLineBreaks(elements: Element[]): Element[] {
+  let first = 0;
+  while (first < elements.length && elements[first]?.element === "line-break") {
+    first++;
+  }
+
+  return first > 0 ? elements.slice(first) : elements;
+}