@wdprlib/parser 3.2.0 → 4.0.0

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

@@ -1,327 +0,0 @@
-/**
- *
- * 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

@@ -1,153 +0,0 @@
-/**
- *
- * 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,
-    };
-  },
-};

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

@@ -1,140 +0,0 @@
-/**
- *
- * Parses the Wikidot inline color syntax: `##color|text##`.
- *
- * This syntax applies a CSS color to inline text. The color specifier
- * and the text content are separated by a pipe (`|`). Both parts are
- * required; an empty color or empty content causes the parse to fail.
- *
- * Supported color formats:
- * - 3-digit hex (e.g. `c00`) -- automatically prefixed with `#`
- * - 6-digit hex (e.g. `cc0000`) -- automatically prefixed with `#`
- * - Named CSS colors (e.g. `blue`, `red`)
- * - CSS color functions (e.g. `rgb(255,0,0)`)
- *
- * Wikidot syntax examples:
- * - `##c00|Apple##` -- red text reading "Apple"
- * - `##blue|Ocean##` -- blue text reading "Ocean"
- * - `##rgb(0,128,0)|Green text##` -- CSS function color
- *
- * Produces a `"color"` AST element with the resolved color value and
- * nested inline elements.
- *
- * @module
- */
-import type { Element } from "@wdprlib/ast";
-import type { InlineRule, ParseContext, RuleResult } from "../types";
-import { hasClosingMarkerBeforeNewline } from "../types";
-import { parseInlineUntil } from "./utils";
-
-/**
- * Inline rule for parsing `##color|text##` color formatting.
- *
- * Triggered by a `COLOR_MARKER` token (`##`). The rule collects the
- * color specifier until a `PIPE` token, then recursively parses inline
- * content until the closing `##`.
- *
- * Fails if:
- * - No closing `##` is found on the same line
- * - No pipe separator is present
- * - The color specifier or content is empty
- */
-export const colorRule: InlineRule = {
-  name: "color",
-  startTokens: ["COLOR_MARKER"],
-
-  /**
-   * Attempts to parse color formatting at the current position.
-   *
-   * @param ctx - Parse context with token stream and current position
-   * @returns A successful result with a `"color"` element, or `{ success: false }`
-   */
-  parse(ctx: ParseContext): RuleResult<Element> {
-    // Check if closing marker exists
-    if (!hasClosingMarkerBeforeNewline({ ...ctx, pos: ctx.pos + 1 }, "COLOR_MARKER")) {
-      return { success: false };
-    }
-
-    let pos = ctx.pos + 1;
-    let consumed = 1; // ##
-
-    // Collect color specification until PIPE
-    let colorSpec = "";
-    while (pos < ctx.tokens.length) {
-      const token = ctx.tokens[pos];
-      if (
-        !token ||
-        token.type === "PIPE" ||
-        token.type === "COLOR_MARKER" ||
-        token.type === "NEWLINE" ||
-        token.type === "EOF"
-      ) {
-        break;
-      }
-      colorSpec += token.value;
-      pos++;
-      consumed++;
-    }
-
-    // Must have a PIPE separator
-    if (ctx.tokens[pos]?.type !== "PIPE") {
-      return { success: false };
-    }
-    pos++;
-    consumed++;
-
-    // Parse inline content until closing ##
-    const contentResult = parseInlineUntil({ ...ctx, pos }, "COLOR_MARKER");
-    pos += contentResult.consumed;
-    consumed += contentResult.consumed;
-
-    // Consume closing ##
-    if (ctx.tokens[pos]?.type === "COLOR_MARKER") {
-      pos++;
-      consumed++;
-    } else {
-      return { success: false };
-    }
-
-    const textChildren = contentResult.elements;
-
-    const trimmedColor = colorSpec.trim();
-
-    // Wikidot requires non-empty color spec and non-empty content
-    if (trimmedColor === "" || textChildren.length === 0) {
-      return { success: false };
-    }
-
-    return {
-      success: true,
-      elements: [
-        {
-          element: "color",
-          data: {
-            color: hexifyColor(trimmedColor),
-            elements: textChildren,
-          },
-        },
-      ],
-      consumed,
-    };
-  },
-};
-
-/**
- * Normalizes shorthand hex color values by prepending a `#` sign.
- *
- * Wikidot allows users to write hex colors without the `#` prefix
- * (e.g. `c00` or `ff0000`). This function detects 3- or 6-character
- * hex strings and adds the prefix. Non-hex color values (named colors,
- * CSS functions) are returned unchanged.
- *
- * @param color - The trimmed color string from the markup
- * @returns The color string, with `#` prepended if it was a bare hex value
- */
-function hexifyColor(color: string): string {
-  if (/^[a-fA-F0-9]{3}$/.test(color) || /^[a-fA-F0-9]{6}$/.test(color)) {
-    return `#${color}`;
-  }
-  return color;
-}