@wdprlib/parser 3.1.2 → 3.2.0

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

@@ -0,0 +1,183 @@
+/**
+ *
+ * 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 -- it is collected as raw text.
+ *
+ * An optional name parameter after "math" can be used to label the
+ * equation (e.g. `[[math euler]]`). This name can then be referenced
+ * elsewhere in the document.
+ *
+ * Special handling for BACKSLASH_BREAK tokens: the preprocessor converts
+ * `\\\n` (LaTeX line break followed by newline) into a special token.
+ * Inside math blocks, this must be restored to `\\\n` since it is valid
+ * LaTeX, not a Wikidot line continuation.
+ *
+ * Empty math blocks (no LaTeX content after trimming) are treated as
+ * invalid and the rule fails.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+import { parseBlockName } from "./utils";
+
+/**
+ * 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;
+
+    // Parse block name
+    const nameResult = parseBlockName(ctx, pos);
+    if (!nameResult || nameResult.name.toLowerCase() !== "math") {
+      return { success: false };
+    }
+    pos += nameResult.consumed;
+    consumed += nameResult.consumed;
+
+    // Skip whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Parse optional name
+    let name: string | null = null;
+    const nameToken = ctx.tokens[pos];
+    if (nameToken?.type === "IDENTIFIER" || nameToken?.type === "TEXT") {
+      let nameParts = "";
+      while (pos < ctx.tokens.length) {
+        const token = ctx.tokens[pos];
+        if (
+          !token ||
+          token.type === "BLOCK_CLOSE" ||
+          token.type === "WHITESPACE" ||
+          token.type === "NEWLINE"
+        ) {
+          break;
+        }
+        nameParts += token.value;
+        pos++;
+        consumed++;
+      }
+      if (nameParts) {
+        name = nameParts;
+      }
+    }
+
+    // Skip whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Expect ]]
+    if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Skip newline after opening tag
+    if (ctx.tokens[pos]?.type === "NEWLINE") {
+      pos++;
+      consumed++;
+    }
+
+    // Collect LaTeX content until [[/math]]
+    // BACKSLASH_BREAK (U+E000) was created by preprocessing from "\\\n"
+    // In math blocks, we need to restore this as "\\\n" for LaTeX line breaks
+    let latexSource = "";
+
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token) break;
+
+      // Check for closing [[/math]]
+      if (token.type === "BLOCK_END_OPEN") {
+        const closeNameResult = parseBlockName(ctx, pos + 1);
+        if (closeNameResult?.name.toLowerCase() === "math") {
+          break;
+        }
+      }
+
+      // Restore BACKSLASH_BREAK to original "\\\n" for LaTeX
+      if (token.type === "BACKSLASH_BREAK") {
+        latexSource += "\\\n";
+      } else {
+        latexSource += token.value;
+      }
+      pos++;
+      consumed++;
+    }
+
+    // Diagnostic for missing close tag
+    if (ctx.tokens[pos]?.type !== "BLOCK_END_OPEN") {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: "Missing closing tag [[/math]] for [[math]]",
+        position: openToken.position,
+      });
+    }
+
+    // Consume [[/math]]
+    if (ctx.tokens[pos]?.type === "BLOCK_END_OPEN") {
+      pos++;
+      consumed++;
+      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") {
+        pos++;
+        consumed++;
+      }
+    }
+
+    // Trim the LaTeX source
+    latexSource = latexSource.trim();
+
+    // Empty math is invalid
+    if (!latexSource) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "math",
+          data: {
+            name,
+            "latex-source": latexSource,
+          },
+        },
+      ],
+      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;
+}

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

@@ -0,0 +1,34 @@
+/**
+ *
+ * Parser rule for the Wikidot `[[module Categories]]` block.
+ *
+ * Displays a list of page categories on the site. Accepts an optional
+ * `include-hidden` boolean attribute to control whether hidden categories
+ * (those prefixed with `_`) are shown.
+ *
+ * @module
+ */
+
+import type { ModuleRule } from "../types";
+import { parseBool } from "../utils";
+import type { CategoriesModuleData } from "./types";
+
+/**
+ * Module rule for `[[module Categories]]`.
+ *
+ * Parses the `include-hidden` attribute (accepts both `include-hidden` and
+ * `includehidden` forms, since Wikidot lowercases all attribute names).
+ * Defaults to false.
+ */
+export const categoriesModuleRule: ModuleRule = {
+  name: "module-categories",
+  acceptsNames: ["categories"],
+  hasBody: false,
+
+  parse(_ctx, _pos, args): CategoriesModuleData {
+    return {
+      module: "categories",
+      "include-hidden": parseBool(args["include-hidden"] ?? args.includehidden, false),
+    };
+  },
+};

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

@@ -0,0 +1,21 @@
+/**
+ *
+ * Type definitions for the Categories module.
+ *
+ * The `[[module Categories]]` block displays a list of page categories
+ * on the current site.
+ *
+ * @module
+ */
+
+/**
+ * AST data for a `[[module Categories]]` element.
+ *
+ * The rendering application should query the site's category list and
+ * display them, optionally including hidden categories.
+ */
+export interface CategoriesModuleData {
+  module: "categories";
+  /** Whether to include hidden categories (prefixed with `_`) in the listing */
+  "include-hidden": boolean;
+}

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

@@ -0,0 +1,37 @@
+/**
+ *
+ * Parser rule for the Wikidot `[[module CSS]]` block.
+ *
+ * Allows embedding custom CSS styles within a Wikidot page. The module body
+ * contains raw CSS text that is emitted as a `style` element in the AST.
+ *
+ * @example
+ * ```
+ * [[module CSS]]
+ * .custom-class { color: red; }
+ * [[/module]]
+ * ```
+ *
+ * @module
+ */
+
+import type { Element } from "@wdprlib/ast";
+import type { ModuleRule } from "../types";
+
+/**
+ * Module rule for `[[module CSS]]`.
+ *
+ * Unlike most modules that produce a `Module` AST node, the CSS module
+ * produces a direct `style` Element. This is because CSS content is not
+ * a Wikidot module that needs external data resolution -- it can be
+ * rendered immediately as a `<style>` tag.
+ */
+export const cssModuleRule: ModuleRule = {
+  name: "module-css",
+  acceptsNames: ["css"],
+  hasBody: true,
+
+  parse(_ctx, _pos, _args, body): Element {
+    return { element: "style", data: body ?? "" };
+  },
+};

package/src/parser/rules/block/module/iftags/condition.ts

@@ -0,0 +1,109 @@
+/**
+ *
+ * Parsing and evaluation of `[[iftags]]` condition strings.
+ *
+ * The condition string uses a simple syntax where each whitespace-separated
+ * token is a tag name with an optional prefix:
+ * - `+tag` - Tag must be present (AND condition)
+ * - `-tag` - Tag must be absent (NOT condition)
+ * - `tag` - At least one bare tag must be present (OR condition)
+ *
+ * All three categories must independently be satisfied:
+ * required (AND) + forbidden (AND) + optional (OR).
+ *
+ * @module
+ */
+
+import type { TagCondition } from "./types";
+
+/**
+ * Parse iftags condition string into structured format
+ *
+ * @param condition - Raw condition string like "+fruit -admin component"
+ * @returns Parsed condition with required, forbidden, and optional tags
+ */
+export function parseTagCondition(condition: string): TagCondition {
+  const required: string[] = [];
+  const forbidden: string[] = [];
+  const optional: string[] = [];
+  let hasEmptyRequired = false;
+  let hasEmptyForbidden = false;
+
+  const parts = condition.trim().split(/\s+/);
+
+  for (const part of parts) {
+    if (!part) continue;
+
+    if (part.startsWith("+")) {
+      const tag = part.slice(1);
+      if (tag) required.push(tag);
+      else hasEmptyRequired = true;
+    } else if (part.startsWith("-")) {
+      const tag = part.slice(1);
+      if (tag) forbidden.push(tag);
+      else hasEmptyForbidden = true;
+    } else {
+      optional.push(part);
+    }
+  }
+
+  return { required, forbidden, optional, hasEmptyRequired, hasEmptyForbidden };
+}
+
+/**
+ * Evaluate if a tag condition matches the given tags
+ *
+ * @param condition - Parsed tag condition
+ * @param pageTags - Actual tags on the page
+ * @returns true if condition is satisfied
+ */
+export function evaluateTagCondition(condition: TagCondition, pageTags: string[]): boolean {
+  const noNamedTokens =
+    condition.required.length === 0 &&
+    condition.forbidden.length === 0 &&
+    condition.optional.length === 0;
+
+  // No tokens at all = supercommentout (`[[iftags]]`) → never match.
+  if (noNamedTokens && !condition.hasEmptyRequired && !condition.hasEmptyForbidden) {
+    return false;
+  }
+
+  // A bare `+` (with or without other tokens) means "require an unnamed
+  // tag", which can never be satisfied — the whole condition is Hide.
+  if (condition.hasEmptyRequired) {
+    return false;
+  }
+
+  // `[[iftags - ]]` — bare `-` token alone means "forbid nothing", which
+  // is trivially true, so this is Show Always. When combined with other
+  // tokens the bare `-` adds no constraint, so we fall through to the
+  // standard evaluation below.
+  if (condition.hasEmptyForbidden && noNamedTokens) {
+    return true;
+  }
+
+  const tagSet = new Set(pageTags);
+
+  // All required tags must be present
+  for (const tag of condition.required) {
+    if (!tagSet.has(tag)) {
+      return false;
+    }
+  }
+
+  // All forbidden tags must be absent
+  for (const tag of condition.forbidden) {
+    if (tagSet.has(tag)) {
+      return false;
+    }
+  }
+
+  // At least one optional tag must be present (if any specified)
+  if (condition.optional.length > 0) {
+    if (!condition.optional.some((tag) => tagSet.has(tag))) {
+      return false;
+    }
+  }
+
+  return true;
+}

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

@@ -0,0 +1,26 @@
+/**
+ *
+ * IfTags conditional rendering module for Wikidot's `[[iftags]]` block.
+ *
+ * Enables conditional content display based on the current page's tags.
+ * The condition syntax supports required tags (`+tag` or bare `tag`) and
+ * forbidden tags (`-tag`). Content inside the block is only rendered when
+ * all conditions are satisfied.
+ *
+ * Exports condition parsing, evaluation, and AST resolution functions.
+ *
+ * @module
+ */
+
+// Types
+export type { TagCondition, IfTagsResolver } from "./types";
+
+// Condition parsing and evaluation
+export { parseTagCondition, evaluateTagCondition } from "./condition";
+
+// Resolution
+export type { IfTagsData, IfTagsResolveResult } from "./resolve";
+export { isIfTagsElement, resolveIfTags } from "./resolve";
+
+// Source-level preprocessing (must run after include expansion, before parse)
+export { preprocessIftags } from "./preprocess";

package/src/parser/rules/block/module/iftags/preprocess.ts

@@ -0,0 +1,140 @@
+/**
+ *
+ * Text-level expansion of `[[iftags]]` blocks before parsing.
+ *
+ * Unlike the AST-level {@link resolveIfTags} resolver, which evaluates
+ * `if-tags` nodes after parsing, this pass operates directly on the
+ * raw wikitext source. The difference matters for templates that embed
+ * an `[[iftags]]` block inside another construct's attribute string,
+ * for example:
+ *
+ * ```wikitext
+ * [[div_ class="x" [[iftags +foo]]style="display:none;"[[/iftags]]]]
+ * ```
+ *
+ * The block-level tokenizer cannot recover a well-formed opener from
+ * that input — the inner `[[iftags ...]]X[[/iftags]]` has to collapse
+ * to either `X` or the empty string *before* the parser sees the outer
+ * tag, so the attribute string becomes plain text again.
+ *
+ * `pageTags` semantics:
+ *
+ * - `string[]`: full pass. Every `[[iftags]]` is evaluated against the
+ *   given tag set and collapses to either its body or the empty string.
+ *   The AST will contain no `if-tags` nodes after parsing.
+ * - `null`: tags are unknown (e.g. draft preview, fixture test).
+ *   The pass still runs but only collapses `[[iftags]]` blocks that are
+ *   embedded inside another block's opener (`[[name ... [[iftags ...]]X[[/iftags]] ... ]]`).
+ *   Block-level `[[iftags]]` are left alone for {@link resolveIfTags}
+ *   to evaluate later when real tags are supplied via `getPageTags`.
+ *   Opener-embedded iftags are collapsed using an empty-tag assumption
+ *   (i.e. `+tag` conditions fail, `-tag` conditions pass). This is a
+ *   lossy fallback that keeps the outer block parseable; callers that
+ *   need accurate rendering should pass the real tags as `string[]`.
+ *
+ * Pipeline order (when invoked via `parse()`):
+ *
+ * ```
+ * getPageTags → resolveIncludes → parse({ pageTags }) → resolveModules
+ * ```
+ *
+ * Running this after include expansion is intentional: an included
+ * page may itself embed `[[iftags]]`, and the condition is evaluated
+ * against the *including* page's tags, not the included page's.
+ *
+ * @module
+ */
+
+import { parseTagCondition, evaluateTagCondition } from "./condition";
+import {
+  computeBracketDepths,
+  makeUniqueSentinels,
+  maskRawRegions,
+  restorePlaceholders,
+} from "../../../../preprocess/utils";
+
+/**
+ * Matches one `[[iftags ...]]X[[/iftags]]` where `X` contains no further
+ * `[[iftags]]` opener or closer. Used for innermost-first reduction.
+ *
+ * - `g` (global): a single `replace` pass rewrites every innermost block,
+ *   so sibling blocks collapse together and the reduction loop runs once
+ *   per nesting level rather than once per block.
+ * - `i` (case-insensitive): Wikidot block names are case-insensitive
+ * - `s` (dot matches newline): bodies can span multiple lines
+ * - `[^\]]*` for the condition: tag-condition tokens (`+tag`, `-tag`,
+ *   bare names) never contain `]`, and stopping at the first `]` keeps
+ *   the regex linear in body length even on degenerate input.
+ */
+const INNERMOST_IFTAGS_PATTERN =
+  /\[\[\s*iftags\b([^\]]*)\]\]((?:(?!\[\[\s*iftags\b|\[\[\/\s*iftags\s*\]\]).)*)\[\[\/\s*iftags\s*\]\]/gis;
+
+/**
+ * Expand `[[iftags ...]]X[[/iftags]]` directives in `source` against the
+ * current page's tags.
+ *
+ * Behaviour:
+ * - Raw regions (`[[code]]`, `[[html]]`, `@@...@@`, `@<...>@`) are
+ *   protected: literal `[[iftags]]` tokens inside them are not expanded.
+ * - Nested `[[iftags]]` are processed innermost-first, so an outer
+ *   block can re-process the now-flattened inner body uniformly.
+ * - `pageTags === null`: only `[[iftags]]` blocks embedded inside
+ *   another block's opener are collapsed (using an empty-tag fallback
+ *   so `+tag` conditions fail and `-tag` conditions pass). Block-level
+ *   iftags are left intact for the AST-level resolver.
+ *
+ * @param source   Raw wikitext (typically after include expansion).
+ * @param pageTags Tags of the page being rendered, or `null` for the
+ *                 opener-embedded-only fallback mode.
+ * @returns Source with matching iftags replaced by their bodies and
+ *          unmatched iftags removed entirely.
+ */
+export function preprocessIftags(source: string, pageTags: string[] | null): string {
+  if (!source.includes("[[")) return source; // fast path
+
+  const sentinels = makeUniqueSentinels(source);
+  const { masked, placeholders } = maskRawRegions(source, sentinels);
+  const reduced = reduceIftags(masked, pageTags);
+  return restorePlaceholders(reduced, placeholders, sentinels);
+}
+
+/**
+ * Replace `[[iftags ...]]X[[/iftags]]` blocks innermost-first until no
+ * iftags pair remains.
+ *
+ * Behaviour by `pageTags`:
+ * - `string[]`: every match collapses to body / empty based on tag membership.
+ * - `null`: only matches whose start offset has `bracketDepth > 0`
+ *   (i.e. embedded inside an outer block opener) are collapsed, using
+ *   an empty-tag assumption. Block-level matches are returned verbatim
+ *   so {@link resolveIfTags} can evaluate them later.
+ *
+ * The loop terminates when a pass changes nothing.
+ */
+function reduceIftags(source: string, pageTags: string[] | null): string {
+  let current = source;
+  // Worst-case bound: one pass eliminates at least one nesting level, and
+  // nesting depth is at most `source.length`. The explicit cap stops a
+  // runaway regex (e.g. pathological zero-width match) from looping forever.
+  const maxIterations = source.length + 1;
+  const tagSet: string[] = pageTags ?? [];
+  for (let i = 0; i < maxIterations; i++) {
+    const depths = pageTags === null ? computeBracketDepths(current) : null;
+    let changed = false;
+    const next = current.replace(
+      INNERMOST_IFTAGS_PATTERN,
+      (match, cond: string, body: string, offset: number) => {
+        if (depths !== null && depths[offset] === 0) {
+          // block-level iftags in `null` mode → leave for AST resolver
+          return match;
+        }
+        changed = true;
+        const condition = parseTagCondition(cond);
+        return evaluateTagCondition(condition, tagSet) ? body : "";
+      },
+    );
+    if (!changed) return current;
+    current = next;
+  }
+  return current;
+}

package/src/parser/rules/block/module/iftags/resolve.ts

@@ -0,0 +1,73 @@
+/**
+ *
+ * Resolution of `[[iftags]]` conditional blocks.
+ *
+ * During the resolve phase, each `[[iftags]]` element is evaluated against
+ * the current page's tags. If the condition matches, the element's children
+ * are included in the output; otherwise, they are omitted. If page tags are
+ * not available (null), the element is kept as-is for later resolution.
+ *
+ * @module
+ */
+
+import type { Element } from "@wdprlib/ast";
+import { parseTagCondition, evaluateTagCondition } from "./condition";
+
+/**
+ * Data structure for an `[[iftags]]` element in the AST.
+ */
+export interface IfTagsData {
+  condition: string;
+  elements: Element[];
+}
+
+/**
+ * Result of attempting to resolve an `[[iftags]]` element.
+ *
+ * The `evaluated` flag indicates whether the condition was actually tested.
+ * When `pageTags` is null (tags not available), the condition is not evaluated
+ * and the element should be kept in the AST for later resolution.
+ */
+export interface IfTagsResolveResult {
+  /**
+   * Whether the condition was evaluated
+   * - true: condition was evaluated (pageTags provided)
+   * - false: pageTags was null, element kept as-is
+   */
+  evaluated: boolean;
+
+  /**
+   * Whether the condition matched (only meaningful if evaluated=true)
+   */
+  matched: boolean;
+}
+
+/**
+ * Type guard to check if an element is an `[[iftags]]` element.
+ *
+ * @param element - The element to check
+ * @returns true if the element has `element: "if-tags"` and appropriate data structure
+ */
+export function isIfTagsElement(
+  element: Element,
+): element is Element & { element: "if-tags"; data: IfTagsData } {
+  return element.element === "if-tags";
+}
+
+/**
+ * Evaluate an iftags condition against page tags
+ *
+ * @param data - IfTags element data with condition and child elements
+ * @param pageTags - Current page's tags, or null if not available
+ * @returns Result indicating if evaluated and if matched
+ */
+export function resolveIfTags(data: IfTagsData, pageTags: string[] | null): IfTagsResolveResult {
+  if (pageTags === null) {
+    return { evaluated: false, matched: false };
+  }
+
+  const condition = parseTagCondition(data.condition);
+  const matched = evaluateTagCondition(condition, pageTags);
+
+  return { evaluated: true, matched };
+}