@wdprlib/parser 3.2.0 → 4.0.0

package/src/parser/rules/common/block-name.ts

@@ -0,0 +1,33 @@
+import type { ParseContext } from "../types";
+
+/**
+ * Parse block name from tokens (handles [[name or [[/name).
+ *
+ * Handles underscore suffix like "div_" which may be tokenized as
+ * [IDENTIFIER "div"] [UNDERSCORE "_"].
+ */
+export function parseBlockName(
+  ctx: ParseContext,
+  startPos: number,
+): { name: string; consumed: number } | null {
+  let pos = startPos;
+  let consumed = 0;
+
+  // Wikidot does NOT allow whitespace between [[ and block name.
+  // e.g. [[ code ]] is treated as plain text, not a code block.
+  const token = ctx.tokens[pos];
+  if (!token || (token.type !== "TEXT" && token.type !== "IDENTIFIER")) {
+    return null;
+  }
+
+  let name = token.value.toLowerCase();
+  consumed++;
+  pos++;
+
+  if (ctx.tokens[pos]?.type === "UNDERSCORE") {
+    name += "_";
+    consumed++;
+  }
+
+  return { name, consumed };
+}

package/src/parser/rules/common/index.ts

@@ -0,0 +1,2 @@
+export { filterUnsafeAttributes } from "./attribute-safety";
+export { parseBlockName } from "./block-name";

package/src/parser/rules/contracts/index.ts

@@ -0,0 +1,3 @@
+export type { ParseContext } from "./parse-context";
+export type { BlockRule, InlineRule, RuleResult } from "./rule";
+export type { ScopeContext } from "./scope";

package/src/parser/rules/contracts/parse-context.ts

@@ -0,0 +1,38 @@
+import type { Token } from "../../../lexer";
+import type {
+  CodeBlockData,
+  Diagnostic,
+  Element,
+  TocEntry,
+  Version,
+  WikitextSettings,
+} from "@wdprlib/ast";
+import type { BlockRule, InlineRule } from "./rule";
+import type { ScopeContext } from "./scope";
+
+/**
+ * Parser context passed to rules.
+ *
+ * Fields are grouped by lifecycle:
+ * - Static config (`tokens`, `version`, `trackPositions`, `settings`, rule arrays).
+ * - `pos`: per-scope cursor; kept top-level because every rule spread overrides it.
+ * - Accumulators (`footnotes`, `tocEntries`, ..., `diagnostics`): shared by array identity.
+ * - `scope`: per-scope state with immutable-replace semantics.
+ */
+export interface ParseContext {
+  tokens: Token[];
+  pos: number;
+  version: Version;
+  trackPositions: boolean;
+  settings: WikitextSettings;
+  footnotes: Element[][];
+  tocEntries: TocEntry[];
+  codeBlocks: CodeBlockData[];
+  htmlBlocks: string[];
+  bibcites: string[];
+  blockRules: BlockRule[];
+  blockFallbackRule: BlockRule;
+  inlineRules: InlineRule[];
+  diagnostics: Diagnostic[];
+  scope: ScopeContext;
+}

package/src/parser/rules/contracts/rule.ts

@@ -0,0 +1,43 @@
+import type { Element } from "@wdprlib/ast";
+import type { TokenType } from "../../../lexer";
+import type { ParseContext } from "./parse-context";
+
+/**
+ * Result of a rule attempt.
+ */
+export type RuleResult<T> = { success: true; elements: T[]; consumed: number } | { success: false };
+
+/**
+ * Block rule interface.
+ */
+export interface BlockRule {
+  /** Rule name for debugging. */
+  name: string;
+  /** Token types that can start this rule. */
+  startTokens: TokenType[];
+  /** Whether this rule requires line start. */
+  requiresLineStart: boolean;
+  /** Try to parse this block. */
+  parse(ctx: ParseContext): RuleResult<Element>;
+  /**
+   * Check if tokens at the given position match this rule's start pattern.
+   * Used by inline parser to determine behavior before a block boundary.
+   */
+  isStartPattern?(ctx: ParseContext, pos: number): boolean;
+  /**
+   * When true, a single newline before this block becomes a line-break.
+   */
+  preservesPrecedingLineBreak?: boolean;
+}
+
+/**
+ * Inline rule interface.
+ */
+export interface InlineRule {
+  /** Rule name for debugging. */
+  name: string;
+  /** Token types that can start this rule. */
+  startTokens: TokenType[];
+  /** Try to parse this inline element. */
+  parse(ctx: ParseContext): RuleResult<Element>;
+}

package/src/parser/rules/contracts/scope.ts

@@ -0,0 +1,31 @@
+import type { ParseContext } from "./parse-context";
+
+/**
+ * Per-scope state propagated by spread + override semantics.
+ *
+ * Every field is `readonly` so a rule cannot accidentally mutate the
+ * parent scope by writing through a shared reference. Updates must be
+ * expressed as a replacement: `ctx.scope = { ...ctx.scope, X: ... }`.
+ */
+export interface ScopeContext {
+  /**
+   * Close condition for the current block. The paragraph parser calls
+   * it to decide when to stop collecting inline content.
+   */
+  readonly blockCloseCondition?: (ctx: ParseContext) => boolean;
+  /**
+   * Block names excluded from paragraph-boundary detection.
+   */
+  readonly excludedBlockNames?: ReadonlySet<string>;
+  /**
+   * Budget for div nesting: tracks how many more nested divs can open.
+   */
+  readonly divClosesBudget?: number;
+  /**
+   * Used by the footnote-block rule to reject duplicate top-level occurrences.
+   *
+   * Scope is per spread copy of `ParseContext`, not document-global. This keeps
+   * the original primitive semantics while avoiding rollback-unsafe shared state.
+   */
+  readonly footnoteBlockParsed: boolean;
+}

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

@@ -0,0 +1,54 @@
+import { sanitizeUrl as braintreeSanitizeUrl } from "@braintree/sanitize-url";
+
+export type AnchorTarget = "new-tab" | "parent" | "top" | "same";
+
+export interface AnchorAttributes {
+  target: AnchorTarget | null;
+  attributes: Record<string, string>;
+}
+
+export function buildAnchorAttributes(attrs: Record<string, string>): AnchorAttributes {
+  const target = parseAnchorTarget(attrs.target);
+  const { target: _target, ...cleanAttrs } = attrs;
+
+  if (cleanAttrs.href) {
+    cleanAttrs.href = sanitizeUrl(cleanAttrs.href);
+  }
+
+  return { target, attributes: cleanAttrs };
+}
+
+function parseAnchorTarget(targetAttr: string | undefined): AnchorTarget | null {
+  if (targetAttr === "_blank") return "new-tab";
+  if (targetAttr === "_parent") return "parent";
+  if (targetAttr === "_top") return "top";
+  if (targetAttr === "_self") return "same";
+  return null;
+}
+
+function sanitizeUrl(url: string): string {
+  const normalizedForCheck = stripControlAndWhitespace(url).toLowerCase();
+  const dangerousSchemes = ["javascript:", "data:", "vbscript:"];
+  for (const scheme of dangerousSchemes) {
+    if (normalizedForCheck.startsWith(scheme)) {
+      return "#invalid-url";
+    }
+  }
+
+  const sanitized = braintreeSanitizeUrl(url);
+  return sanitized === "about:blank" ? "#invalid-url" : url;
+}
+
+const WHITESPACE = /\s/;
+
+function stripControlAndWhitespace(value: string): string {
+  let result = "";
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (WHITESPACE.test(char) || code <= 0x1f) {
+      continue;
+    }
+    result += char;
+  }
+  return result;
+}

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

@@ -0,0 +1,26 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { inlineRules } from "../index";
+import { getCandidateInlineRules } from "../utils";
+
+export interface AnchorChildResult {
+  elements: Element[];
+  consumed: number;
+}
+
+export function parseAnchorChild(ctx: ParseContext, pos: number): AnchorChildResult {
+  const token = ctx.tokens[pos];
+  if (!token) {
+    return { elements: [], consumed: 0 };
+  }
+
+  const inlineCtx: ParseContext = { ...ctx, pos };
+  for (const rule of getCandidateInlineRules(inlineRules, token.type)) {
+    const result = rule.parse(inlineCtx);
+    if (result.success) {
+      return { elements: result.elements, consumed: result.consumed };
+    }
+  }
+
+  return { elements: [{ element: "text", data: token.value }], consumed: 1 };
+}

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

@@ -0,0 +1,34 @@
+import type { ParseContext } from "../../types";
+import { isAnchorBlockName, parseAnchorBlockName } from "./syntax";
+
+export function tryConsumeAnchorClose(
+  ctx: ParseContext,
+  pos: number,
+  paragraphStrip: boolean,
+): { consumed: number } | null {
+  if (ctx.tokens[pos]?.type !== "BLOCK_END_OPEN") {
+    return null;
+  }
+
+  const closeNameResult = parseAnchorBlockName(ctx, pos + 1);
+  if (!closeNameResult || !isAnchorBlockName(closeNameResult.name)) {
+    return null;
+  }
+
+  let consumed = 1 + closeNameResult.consumed;
+  let closePos = pos + consumed;
+  if (ctx.tokens[closePos]?.type === "BLOCK_CLOSE") {
+    closePos++;
+    consumed++;
+  }
+
+  if (
+    paragraphStrip &&
+    ctx.tokens[closePos]?.type === "NEWLINE" &&
+    ctx.tokens[closePos + 1]?.type !== "NEWLINE"
+  ) {
+    consumed++;
+  }
+
+  return { consumed };
+}

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

@@ -0,0 +1,59 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseAnchorChild } from "./child";
+import { tryConsumeAnchorClose } from "./close";
+import { consumeAnchorNewline } from "./newline";
+import { trimParagraphStripLineBreaks } from "./paragraph-strip";
+
+export interface AnchorContentResult {
+  children: Element[];
+  consumed: number;
+  foundClose: boolean;
+}
+
+export function parseAnchorContent(
+  ctx: ParseContext,
+  startPos: number,
+  paragraphStrip: boolean,
+): AnchorContentResult {
+  const children: Element[] = [];
+  let pos = startPos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") {
+      break;
+    }
+
+    const closeResult = tryConsumeAnchorClose(ctx, pos, paragraphStrip);
+    if (closeResult !== null) {
+      trimParagraphStripLineBreaks(children, paragraphStrip);
+      return {
+        children,
+        consumed: consumed + closeResult.consumed,
+        foundClose: true,
+      };
+    }
+
+    if (token.type === "NEWLINE") {
+      const newline = consumeAnchorNewline(ctx, pos, paragraphStrip, children);
+      pos += newline.consumed;
+      consumed += newline.consumed;
+      continue;
+    }
+
+    if (token.type === "WHITESPACE" && token.lineStart) {
+      pos++;
+      consumed++;
+      continue;
+    }
+
+    const child = parseAnchorChild(ctx, pos);
+    children.push(...child.elements);
+    pos += child.consumed;
+    consumed += child.consumed;
+  }
+
+  return { children, consumed, foundClose: false };
+}

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

@@ -0,0 +1,103 @@
+/**
+ *
+ * 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 { buildAnchorAttributes } from "./attributes";
+import { parseAnchorContent } from "./content";
+import { parseAnchorOpen } from "./open";
+
+/**
+ * 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 };
+    }
+
+    const openResult = parseAnchorOpen(ctx);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    const contentResult = parseAnchorContent(ctx, openResult.bodyStart, openResult.paragraphStrip);
+    const consumed = openResult.consumed + contentResult.consumed;
+
+    if (!contentResult.foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: `Missing closing tag [[/a]] for [[${openResult.name}]]`,
+        position: openToken.position,
+      });
+      return { success: false };
+    }
+
+    const anchorAttrs = buildAnchorAttributes(openResult.attributes);
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "anchor",
+          data: {
+            target: anchorAttrs.target,
+            attributes: anchorAttrs.attributes,
+            elements: contentResult.children,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

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

@@ -0,0 +1,26 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+
+export interface AnchorNewlineResult {
+  consumed: number;
+}
+
+export function consumeAnchorNewline(
+  ctx: ParseContext,
+  pos: number,
+  paragraphStrip: boolean,
+  children: Element[],
+): AnchorNewlineResult {
+  let consumed = 1;
+  let nextPos = pos + 1;
+
+  if (!paragraphStrip) {
+    children.push({ element: "line-break" });
+    while (ctx.tokens[nextPos]?.type === "WHITESPACE" && ctx.tokens[nextPos]?.lineStart) {
+      nextPos++;
+      consumed++;
+    }
+  }
+
+  return { consumed };
+}

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

@@ -0,0 +1,47 @@
+import type { ParseContext } from "../../types";
+import { parseAttributes } from "../../block/utils";
+import { isAnchorBlockName, parseAnchorBlockName } from "./syntax";
+
+export interface AnchorOpenResult {
+  name: string;
+  paragraphStrip: boolean;
+  attributes: Record<string, string>;
+  bodyStart: number;
+  consumed: number;
+}
+
+export function parseAnchorOpen(ctx: ParseContext): AnchorOpenResult | null {
+  if (ctx.tokens[ctx.pos]?.type !== "BLOCK_OPEN") {
+    return null;
+  }
+
+  let pos = ctx.pos + 1;
+  let consumed = 1;
+
+  const nameResult = parseAnchorBlockName(ctx, pos);
+  if (!nameResult || !isAnchorBlockName(nameResult.name)) {
+    return null;
+  }
+
+  pos += nameResult.consumed;
+  consumed += nameResult.consumed;
+
+  const attrResult = parseAttributes(ctx, pos);
+  pos += attrResult.consumed;
+  consumed += attrResult.consumed;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  pos++;
+  consumed++;
+
+  return {
+    name: nameResult.name,
+    paragraphStrip: nameResult.paragraphStrip,
+    attributes: attrResult.attrs,
+    bodyStart: pos,
+    consumed,
+  };
+}

package/src/parser/rules/inline/anchor/paragraph-strip.ts

@@ -0,0 +1,14 @@
+import type { Element } from "@wdprlib/ast";
+
+export function trimParagraphStripLineBreaks(children: Element[], paragraphStrip: boolean): void {
+  if (!paragraphStrip) {
+    return;
+  }
+
+  while (children.length > 0 && children[0]?.element === "line-break") {
+    children.shift();
+  }
+  while (children.length > 0 && children[children.length - 1]?.element === "line-break") {
+    children.pop();
+  }
+}

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

@@ -0,0 +1,40 @@
+import type { ParseContext } from "../../types";
+
+export interface AnchorBlockName {
+  name: string;
+  paragraphStrip: boolean;
+  consumed: number;
+}
+
+export function parseAnchorBlockName(ctx: ParseContext, startPos: number): AnchorBlockName | null {
+  let pos = startPos;
+  let consumed = 0;
+
+  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++;
+
+  let paragraphStrip = false;
+  if (ctx.tokens[pos]?.type === "UNDERSCORE") {
+    paragraphStrip = true;
+    name += "_";
+    consumed++;
+  }
+
+  return { name, paragraphStrip, consumed };
+}
+
+export function isAnchorBlockName(name: string): boolean {
+  const baseName = name.replace(/_$/, "");
+  return baseName === "a" || baseName === "anchor";
+}

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

@@ -0,0 +1,38 @@
+/**
+ *
+ * Parses the Wikidot named anchor syntax: `[[# name]]`.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { parseAnchorNameTarget } from "./syntax";
+
+export const anchorNameRule: InlineRule = {
+  name: "anchorName",
+  startTokens: ["BLOCK_OPEN"],
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const target = parseAnchorNameTarget(ctx, ctx.pos + 1);
+    if (!target) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "anchor-name",
+          data: target.name,
+        },
+      ],
+      consumed: 1 + target.consumed,
+    };
+  },
+};

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

@@ -0,0 +1,39 @@
+import type { ParseContext } from "../../types";
+
+export function collectAnchorName(
+  ctx: ParseContext,
+  startPos: number,
+): { name: string; consumed: number } | null {
+  let pos = startPos;
+  let consumed = 0;
+  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;
+    }
+    if (!isValidAnchorNameToken(token.value)) {
+      break;
+    }
+    name += token.value;
+    pos++;
+    consumed++;
+  }
+
+  return name ? { name, consumed } : null;
+}
+
+function isValidAnchorNameToken(value: string): boolean {
+  for (const char of value) {
+    if (!/^[-_A-Za-z0-9.%]$/.test(char)) {
+      return false;
+    }
+  }
+  return true;
+}