@wdprlib/parser 3.1.2 → 3.2.0

package/src/parser/rules/inline/anchor-name.ts

@@ -0,0 +1,154 @@
+/**
+ *
+ * Parses the Wikidot named anchor syntax: `[[# name]]`.
+ *
+ * A named anchor creates an invisible anchor target (`<a id="name">`)
+ * that can be referenced by page-internal links such as `[#name Label]`
+ * or triple-bracket anchor links like `[[[#name]]]`.
+ *
+ * The anchor name must consist exclusively of the characters
+ * `[-_A-Za-z0-9.%]` (matching the original Wikidot regex
+ * `/(\[\[# )([-_A-Za-z0-9.%]+?)(\]\])/i`).
+ *
+ * A whitespace gap is required between the `#` and the name
+ * (`[[# myAnchor]]` is valid; `[[#myAnchor]]` is not).
+ *
+ * Produces an `"anchor-name"` AST element whose `data` field contains
+ * the raw anchor name string.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+
+/**
+ * Tests whether a single character is a valid anchor name character.
+ *
+ * Wikidot restricts anchor names to ASCII alphanumerics, hyphens,
+ * underscores, dots, and percent signs.
+ *
+ * @param char - A single character to validate
+ * @returns `true` if the character is allowed in an anchor name
+ */
+function isValidAnchorChar(char: string): boolean {
+  return /^[-_A-Za-z0-9.%]$/.test(char);
+}
+
+/**
+ * Inline rule for parsing `[[# name]]` named anchor targets.
+ *
+ * Triggered by a `BLOCK_OPEN` (`[[`) token. The rule looks for the `#`
+ * character followed by mandatory whitespace and then the anchor name.
+ *
+ * Parsing steps:
+ * 1. Consume `[[` and optional leading whitespace
+ * 2. Require a `#` token (HASH or TEXT `"#"`)
+ * 3. Require at least one whitespace token after `#`
+ * 4. Collect consecutive valid anchor-name characters as the name
+ * 5. Require closing `]]`
+ *
+ * Fails if the anchor name is empty or if `]]` is not found.
+ */
+export const anchorNameRule: InlineRule = {
+  name: "anchorName",
+  startTokens: ["BLOCK_OPEN"],
+
+  /**
+   * Attempts to parse a `[[# name]]` named anchor at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with an `"anchor-name"` element, or `{ success: 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;
+
+    // Skip whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Check for # (hash) - can be TEXT or HASH token
+    const hashToken = ctx.tokens[pos];
+    if (
+      !hashToken ||
+      (hashToken.type !== "HASH" && !(hashToken.type === "TEXT" && hashToken.value === "#"))
+    ) {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Require whitespace after #
+    if (ctx.tokens[pos]?.type !== "WHITESPACE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Skip additional whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Parse anchor name - collect valid characters until ]]
+    let name = "";
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (
+        !token ||
+        token.type === "BLOCK_CLOSE" ||
+        token.type === "NEWLINE" ||
+        token.type === "EOF"
+      ) {
+        break;
+      }
+      // Check if all characters in token are valid anchor chars
+      const value = token.value;
+      let allValid = true;
+      for (const char of value) {
+        if (!isValidAnchorChar(char)) {
+          allValid = false;
+          break;
+        }
+      }
+      if (!allValid) {
+        break;
+      }
+      name += value;
+      pos++;
+      consumed++;
+    }
+
+    // Anchor name is required
+    if (!name) {
+      return { success: false };
+    }
+
+    // Expect ]]
+    if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "anchor-name",
+          data: name,
+        },
+      ],
+      consumed,
+    };
+  },
+};

package/src/parser/rules/inline/anchor.ts

@@ -0,0 +1,327 @@
+/**
+ *
+ * Parses the Wikidot anchor inline block syntax: `[[a]]...[[/a]]`.
+ *
+ * An anchor wraps inline content in an HTML `<a>` element, allowing
+ * href, target, and other HTML attributes to be specified.
+ *
+ * Wikidot syntax variants:
+ * - `[[a href="url"]]text[[/a]]` -- basic anchor with href
+ * - `[[a_ href="url"]]text[[/a]]` -- paragraph strip mode (trailing underscore)
+ *
+ * Paragraph strip mode (`[[a_]]`) suppresses newlines within the anchor
+ * body and strips at most one trailing newline after the closing tag
+ * (preserving double newlines as paragraph breaks). This prevents
+ * unwanted `<br>` elements when consecutive anchor blocks are placed on
+ * separate lines.
+ *
+ * The `target` attribute is extracted and mapped to a semantic enum value
+ * (`"new-tab"`, `"parent"`, `"top"`, `"same"`), while the remaining
+ * attributes (including `href`) are passed through after URL sanitization.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+import { inlineRules } from "../index";
+import { sanitizeUrl as braintreeSanitizeUrl } from "@braintree/sanitize-url";
+import { parseAttributes } from "../block/utils";
+import { canApplyInlineRule } from "./utils";
+
+/**
+ * Sanitizes a URL to prevent XSS attacks via dangerous URI schemes.
+ *
+ * Applies two layers of protection:
+ * 1. Pre-checks the whitespace-normalized URL against known dangerous schemes
+ *    (`javascript:`, `data:`, `vbscript:`), catching evasion attempts like
+ *    `"java script:"` with embedded whitespace.
+ * 2. Delegates to `@braintree/sanitize-url` for additional validation.
+ *
+ * Returns the original URL (not the normalized form) to avoid unintended
+ * modifications such as trailing-slash addition.
+ *
+ * @param url - The raw URL string to sanitize
+ * @returns The original URL if safe, or `"#invalid-url"` if the URL is deemed dangerous
+ */
+function sanitizeUrl(url: string): string {
+  // Pre-process: normalize whitespace to catch evasion attempts like "java script:"
+  const normalizedForCheck = url.replace(/[\s\u0000-\u001f]/g, "").toLowerCase();
+
+  // Check for dangerous schemes after whitespace normalization
+  const dangerousSchemes = ["javascript:", "data:", "vbscript:"];
+  for (const scheme of dangerousSchemes) {
+    if (normalizedForCheck.startsWith(scheme)) {
+      return "#invalid-url";
+    }
+  }
+
+  // Use library for additional checks
+  const sanitized = braintreeSanitizeUrl(url);
+  if (sanitized === "about:blank") {
+    return "#invalid-url";
+  }
+
+  // Return original URL to avoid unwanted normalization (e.g., trailing slash addition)
+  return url;
+}
+
+/**
+ * Parses the block name portion of an anchor open/close tag, handling the
+ * optional underscore suffix that activates paragraph strip mode.
+ *
+ * Recognizes `a`, `anchor`, `a_`, and `anchor_` (case-insensitive).
+ * The underscore suffix is reported via the `score` field so the caller
+ * can decide how to handle newlines inside the anchor body.
+ *
+ * @param ctx - The current parse context containing the token stream
+ * @param startPos - Token index at which to begin scanning
+ * @returns An object with the lowercased name (including trailing `_` if present),
+ *          a `score` boolean indicating paragraph strip mode, and the number of
+ *          tokens consumed -- or `null` if no valid anchor block name was found
+ */
+function parseAnchorBlockName(
+  ctx: ParseContext,
+  startPos: number,
+): { name: string; score: boolean; consumed: number } | null {
+  let pos = startPos;
+  let consumed = 0;
+
+  // Skip whitespace
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  const token = ctx.tokens[pos];
+  if (!token || (token.type !== "TEXT" && token.type !== "IDENTIFIER")) {
+    return null;
+  }
+
+  let name = token.value.toLowerCase();
+  consumed++;
+  pos++;
+
+  // Check for underscore suffix (paragraph strip)
+  let score = false;
+  if (ctx.tokens[pos]?.type === "UNDERSCORE") {
+    score = true;
+    name += "_";
+    consumed++;
+    pos++;
+  }
+
+  return { name, score, consumed };
+}
+
+/**
+ * Inline rule for parsing `[[a]]...[[/a]]` blocks.
+ *
+ * Triggered by a `BLOCK_OPEN` (`[[`) token. The rule verifies the block name
+ * is `a` or `anchor` (optionally with `_` suffix), parses HTML attributes,
+ * then recursively parses inline content until the matching closing tag.
+ *
+ * Produces an `"anchor"` AST element containing the parsed children, a
+ * semantic `target` value, and the sanitized attribute map.
+ *
+ * Edge cases:
+ * - If no matching closing tag is found, the rule fails (returns `{ success: false }`),
+ *   allowing the tokens to fall through to other rules or the text fallback.
+ * - In paragraph strip mode, newlines within the body are consumed silently
+ *   rather than converted to line-break elements. After the closing tag,
+ *   at most one trailing newline is consumed to prevent a line-break between
+ *   consecutive `[[a_]]` blocks, but double newlines are preserved as
+ *   paragraph breaks.
+ * - The `href` attribute is sanitized to block `javascript:`, `data:`, and
+ *   `vbscript:` schemes.
+ */
+export const anchorRule: InlineRule = {
+  name: "anchor",
+  startTokens: ["BLOCK_OPEN"],
+
+  /**
+   * Attempts to parse an anchor block starting at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with an `"anchor"` element, or `{ success: 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 with flags
+    const nameResult = parseAnchorBlockName(ctx, pos);
+    if (!nameResult) {
+      return { success: false };
+    }
+
+    const baseName = nameResult.name.replace(/_$/, "");
+    if (baseName !== "a" && baseName !== "anchor") {
+      return { success: false };
+    }
+
+    const paragraphStrip = nameResult.score;
+
+    pos += nameResult.consumed;
+    consumed += nameResult.consumed;
+
+    // Parse attributes
+    const attrResult = parseAttributes(ctx, pos);
+    pos += attrResult.consumed;
+    consumed += attrResult.consumed;
+
+    // Expect ]]
+    if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Parse content until [[/a]] or [[/anchor]]
+    const children: Element[] = [];
+    let foundClose = false;
+
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token || token.type === "EOF") {
+        break;
+      }
+
+      // Check for closing tag
+      if (token.type === "BLOCK_END_OPEN") {
+        const closeNameResult = parseAnchorBlockName(ctx, pos + 1);
+        const closeBaseName = closeNameResult?.name.replace(/_$/, "");
+        if (closeNameResult && (closeBaseName === "a" || closeBaseName === "anchor")) {
+          pos++; // [[/
+          consumed++;
+          pos += closeNameResult.consumed;
+          consumed += closeNameResult.consumed;
+          if (ctx.tokens[pos]?.type === "BLOCK_CLOSE") {
+            pos++;
+            consumed++;
+          }
+          foundClose = true;
+
+          // In paragraph strip mode, consume one trailing newline after close tag
+          // This prevents a line-break between consecutive [[a_]] blocks
+          // but preserves paragraph breaks (double newlines)
+          if (
+            paragraphStrip &&
+            ctx.tokens[pos]?.type === "NEWLINE" &&
+            ctx.tokens[pos + 1]?.type !== "NEWLINE"
+          ) {
+            pos++;
+            consumed++;
+          }
+          break;
+        }
+      }
+
+      // Handle NEWLINE
+      if (token.type === "NEWLINE") {
+        if (paragraphStrip) {
+          // Skip newlines in paragraph strip mode
+          pos++;
+          consumed++;
+          continue;
+        }
+        // Convert to line-break
+        children.push({ element: "line-break" });
+        pos++;
+        consumed++;
+        // Skip leading whitespace after newline
+        while (ctx.tokens[pos]?.type === "WHITESPACE" && ctx.tokens[pos]?.lineStart) {
+          pos++;
+          consumed++;
+        }
+        continue;
+      }
+
+      // Skip whitespace at line start
+      if (token.type === "WHITESPACE" && token.lineStart) {
+        pos++;
+        consumed++;
+        continue;
+      }
+
+      // Try each inline rule
+      let matched = false;
+      const inlineCtx: ParseContext = { ...ctx, pos };
+
+      for (const rule of inlineRules) {
+        if (canApplyInlineRule(rule, token)) {
+          const result = rule.parse(inlineCtx);
+          if (result.success) {
+            children.push(...result.elements);
+            pos += result.consumed;
+            consumed += result.consumed;
+            matched = true;
+            break;
+          }
+        }
+      }
+
+      if (!matched) {
+        children.push({ element: "text", data: token.value });
+        pos++;
+        consumed++;
+      }
+    }
+
+    if (!foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: `Missing closing tag [[/a]] for [[${nameResult.name}]]`,
+        position: openToken.position,
+      });
+      return { success: false };
+    }
+
+    // Clean up children - remove leading/trailing line breaks if paragraph strip
+    if (paragraphStrip) {
+      while (children.length > 0 && children[0]?.element === "line-break") {
+        children.shift();
+      }
+      while (children.length > 0 && children[children.length - 1]?.element === "line-break") {
+        children.pop();
+      }
+    }
+
+    // Determine target from attributes
+    let target: "new-tab" | "parent" | "top" | "same" | null = null;
+    const targetAttr = attrResult.attrs.target;
+    if (targetAttr === "_blank") target = "new-tab";
+    else if (targetAttr === "_parent") target = "parent";
+    else if (targetAttr === "_top") target = "top";
+    else if (targetAttr === "_self") target = "same";
+
+    // Remove target from attributes (href stays in attributes)
+    const { target: _t, ...cleanAttrs } = attrResult.attrs;
+
+    // Sanitize href to prevent XSS
+    if (cleanAttrs.href) {
+      cleanAttrs.href = sanitizeUrl(cleanAttrs.href);
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "anchor",
+          data: {
+            target,
+            attributes: cleanAttrs,
+            elements: children,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

package/src/parser/rules/inline/bibcite.ts

@@ -0,0 +1,153 @@
+/**
+ *
+ * Parses the Wikidot bibliography citation syntax: `((bibcite label))`.
+ *
+ * A bibcite creates a numbered inline reference (similar to footnotes)
+ * that links to a corresponding entry in a `[[bibliography]]` block
+ * elsewhere on the page. The `label` string is used to match the
+ * citation with its bibliography entry.
+ *
+ * Unlike most inline blocks that start with `[[`, bibcite uses double
+ * parentheses `((...))` as delimiters. The keyword `bibcite` must
+ * appear (case-insensitive) between the opening `((` and the label.
+ *
+ * Produces a `"bibliography-cite"` AST element. The label is also
+ * pushed into `ctx.bibcites` so the renderer can later resolve
+ * citation numbers.
+ *
+ * Wikidot syntax examples:
+ * - `((bibcite author2024))` -- cite with label "author2024"
+ * - `((bibcite my-source))` -- cite with label "my-source"
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+
+/**
+ * Inline rule for parsing `((bibcite label))` bibliography citations.
+ *
+ * Triggered by a `TEXT` token (specifically the `(` character). The parser
+ * looks for two consecutive `(` tokens, the keyword `bibcite`, the label
+ * text, and then two consecutive `)` tokens.
+ *
+ * The label may span multiple tokens and is trimmed of surrounding whitespace.
+ * Parsing fails if the label is empty or if a newline/EOF is encountered
+ * before the closing `))`.
+ *
+ * Side effect: pushes the label into `ctx.bibcites` for later resolution
+ * during rendering.
+ */
+export const bibciteRule: InlineRule = {
+  name: "bibcite",
+  startTokens: ["TEXT"],
+
+  /**
+   * Attempts to parse a `((bibcite label))` citation at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with a `"bibliography-cite"` element, or `{ success: false }`
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const token = currentToken(ctx);
+
+    // Must start with (
+    if (token.type !== "TEXT" || token.value !== "(") {
+      return { success: false };
+    }
+
+    // Check for second (
+    const nextToken = ctx.tokens[ctx.pos + 1];
+    if (!nextToken || nextToken.type !== "TEXT" || nextToken.value !== "(") {
+      return { success: false };
+    }
+
+    // Check for "bibcite" identifier
+    let pos = ctx.pos + 2;
+    let consumed = 2;
+
+    // Skip whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    const nameToken = ctx.tokens[pos];
+    if (
+      !nameToken ||
+      nameToken.type !== "IDENTIFIER" ||
+      nameToken.value.toLowerCase() !== "bibcite"
+    ) {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Skip whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Parse label (identifier or text)
+    const labelToken = ctx.tokens[pos];
+    if (!labelToken || (labelToken.type !== "IDENTIFIER" && labelToken.type !== "TEXT")) {
+      return { success: false };
+    }
+
+    // Collect label (may span multiple tokens until ))
+    let label = "";
+    let foundClose = false;
+    while (pos < ctx.tokens.length) {
+      const t = ctx.tokens[pos];
+      if (!t) break;
+
+      // Check for ))
+      if (t.type === "TEXT" && t.value === ")") {
+        const nextT = ctx.tokens[pos + 1];
+        if (nextT?.type === "TEXT" && nextT.value === ")") {
+          // Found closing ))
+          consumed += 2;
+          foundClose = true;
+          break;
+        }
+      }
+
+      // Stop at newline or EOF
+      if (t.type === "NEWLINE" || t.type === "EOF") {
+        return { success: false };
+      }
+
+      label += t.value;
+      pos++;
+      consumed++;
+    }
+
+    if (!foundClose) {
+      return { success: false };
+    }
+
+    label = label.trim();
+    if (!label) {
+      return { success: false };
+    }
+
+    // Store bibcite reference in context for later resolution
+    ctx.bibcites.push(label);
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "bibliography-cite",
+          data: {
+            label,
+            brackets: false, // Wikidot adds brackets in output but they're not in the AST
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};