@wdprlib/parser 3.1.2 → 4.0.0

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

@@ -0,0 +1,92 @@
+import type { ParseContext } from "../../types";
+import { currentToken } from "../../types";
+import { parseBlockName } from "../utils";
+
+export interface ModuleBodyResult {
+  body?: string;
+  pos: number;
+  consumed: number;
+}
+
+export function parseModuleBody(
+  ctx: ParseContext,
+  startPos: number,
+  moduleHasBody: boolean,
+): ModuleBodyResult {
+  if (!moduleHasBody || ctx.tokens[startPos]?.type !== "NEWLINE") {
+    return { pos: startPos, consumed: 0 };
+  }
+
+  let pos = startPos + 1;
+  let consumed = 1;
+  const bodyParts: string[] = [];
+  let foundClose = false;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") {
+      break;
+    }
+
+    if (token.type === "BLOCK_END_OPEN") {
+      const closeResult = parseModuleClose(ctx, pos);
+      if (closeResult) {
+        foundClose = true;
+        pos = closeResult.pos;
+        consumed += closeResult.consumed;
+        break;
+      }
+    }
+
+    bodyParts.push(token.value);
+    pos++;
+    consumed++;
+  }
+
+  if (!foundClose) {
+    ctx.diagnostics.push({
+      severity: "warning",
+      code: "unclosed-block",
+      message: "Missing closing tag [[/module]] for [[module]]",
+      position: currentToken(ctx).position,
+    });
+  }
+
+  const trimmed = bodyParts.join("").trim();
+  return {
+    body: trimmed ? trimmed : undefined,
+    pos,
+    consumed,
+  };
+}
+
+function parseModuleClose(
+  ctx: ParseContext,
+  startPos: number,
+): { pos: number; consumed: number } | null {
+  if (ctx.tokens[startPos]?.type !== "BLOCK_END_OPEN") {
+    return null;
+  }
+
+  const closeNameResult = parseBlockName(ctx, startPos + 1);
+  if (
+    !closeNameResult ||
+    (closeNameResult.name !== "module" && closeNameResult.name !== "module654")
+  ) {
+    return null;
+  }
+
+  let pos = startPos + 1 + closeNameResult.consumed;
+  let consumed = 1 + closeNameResult.consumed;
+
+  if (ctx.tokens[pos]?.type === "BLOCK_CLOSE") {
+    pos++;
+    consumed++;
+  }
+  if (ctx.tokens[pos]?.type === "NEWLINE") {
+    pos++;
+    consumed++;
+  }
+
+  return { pos, consumed };
+}

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

@@ -0,0 +1,33 @@
+import type { Element, Module } from "@wdprlib/ast";
+
+export function moduleParseResultToElement(result: Module | Element): Element {
+  if (isElement(result)) {
+    return result;
+  }
+
+  return createModuleElement(result);
+}
+
+export function createUnknownModuleElement(
+  name: string,
+  args: Record<string, string>,
+  body: string | undefined,
+): Element {
+  return createModuleElement({
+    module: "unknown",
+    name,
+    arguments: args,
+    body,
+  });
+}
+
+function createModuleElement(data: Module): Element {
+  return {
+    element: "module",
+    data,
+  };
+}
+
+function isElement(value: Module | Element): value is Element {
+  return "element" in value;
+}

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 };
+}

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

@@ -0,0 +1,63 @@
+/**
+ *
+ * Type definitions for the IfTags conditional rendering module.
+ *
+ * `[[iftags]]` is a Wikidot block that conditionally renders its content
+ * based on the current page's tags. The condition syntax supports required
+ * tags (`+tag`), forbidden tags (`-tag`), and optional tags (bare `tag`).
+ *
+ * @module
+ */
+
+/**
+ * Parsed representation of an `[[iftags +tag -tag ...]]` condition.
+ *
+ * The condition string is parsed into three arrays:
+ * - `required` tags must ALL be present on the page (AND logic, `+tag` syntax)
+ * - `forbidden` tags must ALL be absent from the page (AND logic, `-tag` syntax)
+ * - `optional` tags require at least ONE to be present (OR logic, bare `tag` syntax)
+ *
+ * All three categories must independently be satisfied.
+ *
+ * @example
+ * `[[iftags +fruit -admin component template]]` parses to:
+ * ```
+ * { required: ["fruit"], forbidden: ["admin"], optional: ["component", "template"] }
+ * ```
+ */
+export interface TagCondition {
+  /** Tags that must all be present on the page (`+tag` syntax) */
+  required: string[];
+
+  /** Tags that must all be absent from the page (`-tag` syntax) */
+  forbidden: string[];
+
+  /** Tags where at least one must be present (bare `tag` syntax, OR logic) */
+  optional: string[];
+
+  /**
+   * `true` when the condition contained a bare `+` token (a `+` prefix with
+   * no tag name). Wikidot treats `+` alone as "require an unnamed tag",
+   * which can never be satisfied, so a `+`-only condition evaluates to
+   * `false` (Hide Always).
+   */
+  hasEmptyRequired?: boolean;
+
+  /**
+   * `true` when the condition contained a bare `-` token (a `-` prefix with
+   * no tag name). Wikidot treats `-` alone as "forbid nothing", which is
+   * trivially satisfied — so a `-`-only condition evaluates to `true`
+   * (Show Always).
+   */
+  hasEmptyForbidden?: boolean;
+}
+
+/**
+ * Callback to retrieve the current page's tags during the resolve phase.
+ *
+ * Called when evaluating `[[iftags]]` conditions. The application must provide
+ * this callback with access to the current page's tag list.
+ *
+ * @returns Array of tag names for the current page
+ */
+export type IfTagsResolver = () => string[];