@wdprlib/parser 3.1.2 → 3.2.0

package/src/parser/rules/block/module/listpages/normalize.ts

@@ -0,0 +1,390 @@
+/**
+ *
+ * Query normalization for the ListPages module.
+ *
+ * Converts the raw string-based `ListPagesQuery` (where fields like `tags`,
+ * `category`, and `order` are plain strings) into a `NormalizedListPagesQuery`
+ * with type-safe structured objects. This makes it straightforward for external
+ * applications to build database queries from the normalized representation
+ * without having to re-parse Wikidot's query syntax.
+ *
+ * Based on Wikidot official documentation:
+ * https://www.wikidot.com/doc-modules:listpages-module
+ *
+ * @module
+ */
+
+import type {
+  ListPagesQuery,
+  NormalizedListPagesQuery,
+  NormalizedTags,
+  NormalizedCategory,
+  NormalizedOrder,
+  NormalizedParent,
+  NormalizedDateSelector,
+  NormalizedNumericSelector,
+  OrderField,
+  OrderDirection,
+  DateComparisonOp,
+  NumericComparisonOp,
+} from "./types";
+
+/**
+ * Pattern for splitting multi-value attribute strings.
+ * Wikidot allows commas, semicolons, and whitespace as separators between values.
+ */
+const TOKEN_SEPARATOR = /[,;\s]+/;
+
+/**
+ * Parse tags string into structured format
+ *
+ * Syntax:
+ * - `+tag`: AND condition (must have this tag)
+ * - `-tag`: NOT condition (must not have this tag)
+ * - `tag`: OR condition (any of these tags)
+ * - `=`: same visible tags as current page
+ * - `==`: exact same tags as current page
+ * - `-`: pages with no tags
+ */
+export function parseTags(value: string): NormalizedTags {
+  const result: NormalizedTags = {
+    all: [],
+    any: [],
+    none: [],
+    special: null,
+  };
+
+  const trimmed = value.trim();
+  if (!trimmed) return result;
+
+  // Check for special selectors
+  if (trimmed === "-") {
+    result.special = "none";
+    return result;
+  }
+  if (trimmed === "==") {
+    result.special = "same-all";
+    return result;
+  }
+
+  const tokens = trimmed.split(TOKEN_SEPARATOR).filter(Boolean);
+
+  for (const token of tokens) {
+    if (token === "=") {
+      result.special = "same-visible";
+    } else if (token.startsWith("+")) {
+      const tag = token.slice(1);
+      if (tag) result.all.push(tag);
+    } else if (token.startsWith("-")) {
+      const tag = token.slice(1);
+      if (tag) result.none.push(tag);
+    } else {
+      result.any.push(token);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Parse category string into structured format
+ *
+ * Syntax:
+ * - `*`: all categories
+ * - `.`: current category
+ * - `-category`: exclude category
+ * - `category`: include category
+ * - Multiple categories separated by comma, semicolon, or whitespace
+ */
+export function parseCategory(value: string): NormalizedCategory {
+  const result: NormalizedCategory = {
+    include: [],
+    exclude: [],
+    all: false,
+    current: false,
+  };
+
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) return result;
+
+  if (trimmed === "*") {
+    result.all = true;
+    return result;
+  }
+
+  const tokens = trimmed.split(TOKEN_SEPARATOR).filter(Boolean);
+
+  for (const token of tokens) {
+    if (token === "*") {
+      result.all = true;
+    } else if (token === ".") {
+      result.current = true;
+    } else if (token.startsWith("-")) {
+      const cat = token.slice(1);
+      if (cat) result.exclude.push(cat);
+    } else {
+      result.include.push(token);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Mapping from Wikidot's order field names (both camelCase PHP-style and
+ * snake_case documentation-style) to normalized `OrderField` values.
+ */
+const ORDER_FIELD_MAP: Record<string, OrderField> = {
+  // camelCase format (Wikidot PHP style)
+  datecreated: "created_at",
+  dateedited: "updated_at",
+  title: "title",
+  fullname: "fullname",
+  rating: "rating",
+  votes: "votes",
+  revisions: "revisions",
+  comments: "comments",
+  pagelength: "size",
+  size: "size",
+  random: "random",
+  // snake_case format (documentation style)
+  created_at: "created_at",
+  updated_at: "updated_at",
+};
+
+/**
+ * Parse order string into structured format
+ *
+ * Supports both formats:
+ * - camelCase: `dateCreatedDesc`, `titleAsc`, `ratingDesc`
+ * - Space-separated: `created_at desc`, `title asc`
+ *
+ * Default: { field: "created_at", direction: "desc" }
+ */
+export function parseOrder(value: string): NormalizedOrder {
+  const defaultOrder: NormalizedOrder = { field: "created_at", direction: "desc" };
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed) return defaultOrder;
+
+  // Try space-separated format: "created_at desc"
+  const spaceParts = trimmed.split(/\s+/);
+  if (spaceParts.length >= 2 && spaceParts[0] && spaceParts[1]) {
+    const field = ORDER_FIELD_MAP[spaceParts[0]];
+    const direction = spaceParts[1] === "asc" ? "asc" : "desc";
+    if (field) {
+      return { field, direction };
+    }
+  }
+
+  // Try camelCase format: "dateCreatedDesc"
+  let direction: OrderDirection = "desc";
+  let fieldPart = trimmed;
+
+  if (trimmed.endsWith("desc")) {
+    direction = "desc";
+    fieldPart = trimmed.slice(0, -4);
+  } else if (trimmed.endsWith("asc")) {
+    direction = "asc";
+    fieldPart = trimmed.slice(0, -3);
+  }
+
+  const field = ORDER_FIELD_MAP[fieldPart];
+  if (field) {
+    return { field, direction };
+  }
+
+  // Try single word (field only, use default direction)
+  const singleField = ORDER_FIELD_MAP[trimmed];
+  if (singleField) {
+    return { field: singleField, direction: "desc" };
+  }
+
+  return defaultOrder;
+}
+
+/**
+ * Parse parent string into structured format
+ *
+ * Syntax:
+ * - `-`: orphan pages (no parent)
+ * - `=`: sibling pages (same parent as current)
+ * - `-=`: pages with different parent
+ * - `.`: children of current page
+ * - `page-name`: children of specific page
+ *
+ * Returns undefined for empty/whitespace-only input.
+ */
+export function parseParent(value: string): NormalizedParent | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+
+  switch (trimmed) {
+    case "-":
+      return { type: "none" };
+    case "=":
+      return { type: "same" };
+    case "-=":
+      return { type: "different" };
+    case ".":
+      return { type: "children" };
+    default:
+      return { type: "page", name: trimmed };
+  }
+}
+
+/**
+ * Date comparison operators, ordered longest-first so longer operators
+ * (like `<=`) are matched before shorter ones (like `<`).
+ */
+const DATE_COMPARISON_OPS: DateComparisonOp[] = ["<=", ">=", "<>", "<", ">", "="];
+
+/**
+ * Pattern for relative date expressions like "last 7 days", "last 2 weeks", "last month".
+ * The count is optional and defaults to 1 (e.g., "last month" = "last 1 month").
+ */
+const RELATIVE_DATE_PATTERN = /^last\s+(?:(\d+)\s+)?(day|week|month)s?$/i;
+
+/**
+ * Parse date selector string into structured format
+ *
+ * Syntax:
+ * - `yyyy`: year only
+ * - `yyyy.mm`: year and month
+ * - `>=yyyy.mm.dd`: comparison with date
+ * - `last 7 days`: relative date
+ */
+export function parseDateSelector(value: string): NormalizedDateSelector | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+
+  // Check relative date format: "last 7 days"
+  const relativeMatch = trimmed.match(RELATIVE_DATE_PATTERN);
+  if (relativeMatch && relativeMatch[2]) {
+    const count = relativeMatch[1] ? parseInt(relativeMatch[1], 10) : 1;
+    // Validate count is at least 1
+    if (count < 1) return undefined;
+    const unit = relativeMatch[2].toLowerCase() as "day" | "week" | "month";
+    return { type: "relative", unit, count };
+  }
+
+  // Check comparison operators
+  for (const op of DATE_COMPARISON_OPS) {
+    if (trimmed.startsWith(op)) {
+      const date = trimmed.slice(op.length).trim();
+      if (date) {
+        return { type: "comparison", op, date };
+      }
+    }
+  }
+
+  // Check year format: "2024"
+  if (/^\d{4}$/.test(trimmed)) {
+    return { type: "year", year: parseInt(trimmed, 10) };
+  }
+
+  // Check year.month format: "2024.03"
+  const monthMatch = trimmed.match(/^(\d{4})\.(\d{1,2})$/);
+  if (monthMatch && monthMatch[1] && monthMatch[2]) {
+    const month = parseInt(monthMatch[2], 10);
+    // Validate month is 1-12
+    if (month < 1 || month > 12) return undefined;
+    return {
+      type: "month",
+      year: parseInt(monthMatch[1], 10),
+      month,
+    };
+  }
+
+  return undefined;
+}
+
+/**
+ * Numeric comparison operators, ordered longest-first for correct prefix matching.
+ */
+const NUMERIC_COMPARISON_OPS: NumericComparisonOp[] = ["<=", ">=", "<", ">", "="];
+
+/**
+ * Parse numeric selector string into structured format
+ *
+ * Syntax:
+ * - `5`: equals 5
+ * - `>=10`: greater than or equal to 10
+ * - `<0`: less than 0
+ *
+ * Returns undefined for non-numeric or infinite values.
+ */
+export function parseNumericSelector(value: string): NormalizedNumericSelector | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+
+  // Check comparison operators
+  for (const op of NUMERIC_COMPARISON_OPS) {
+    if (trimmed.startsWith(op)) {
+      const numStr = trimmed.slice(op.length).trim();
+      const num = parseFloat(numStr);
+      // Strict validation: must be finite number and entire string must be numeric
+      if (Number.isFinite(num) && /^-?\d+(\.\d+)?$/.test(numStr)) {
+        return { op, value: num };
+      }
+      return undefined;
+    }
+  }
+
+  // Plain number (equals) - strict validation
+  const num = parseFloat(trimmed);
+  if (Number.isFinite(num) && /^-?\d+(\.\d+)?$/.test(trimmed)) {
+    return { op: "=", value: num };
+  }
+
+  return undefined;
+}
+
+/**
+ * Normalize a ListPagesQuery into structured types
+ *
+ * @param query - Raw query with string fields
+ * @returns Normalized query with structured types
+ */
+export function normalizeQuery(query: ListPagesQuery): NormalizedListPagesQuery {
+  const result: NormalizedListPagesQuery = {};
+
+  // Pass through simple fields
+  if (query.pagetype) result.pagetype = query.pagetype;
+  if (query.linkTo) result.linkTo = query.linkTo;
+  if (query.createdBy) result.createdBy = query.createdBy;
+  if (query.name) result.name = query.name;
+  if (query.fullname) result.fullname = query.fullname;
+  if (query.range) result.range = query.range;
+  if (query.dataFormFields) result.dataFormFields = query.dataFormFields;
+  if (query.offset !== undefined) result.offset = query.offset;
+  if (query.limit !== undefined) result.limit = query.limit;
+  if (query.perPage !== undefined) result.perPage = query.perPage;
+  if (query.reverse !== undefined) result.reverse = query.reverse;
+
+  // Parse complex fields
+  if (query.tags) result.tags = parseTags(query.tags);
+  if (query.category) result.category = parseCategory(query.category);
+  if (query.order) result.order = parseOrder(query.order);
+  if (query.parent) {
+    const parent = parseParent(query.parent);
+    if (parent) result.parent = parent;
+  }
+  if (query.createdAt) {
+    const createdAt = parseDateSelector(query.createdAt);
+    if (createdAt) result.createdAt = createdAt;
+  }
+  if (query.updatedAt) {
+    const updatedAt = parseDateSelector(query.updatedAt);
+    if (updatedAt) result.updatedAt = updatedAt;
+  }
+  if (query.rating) {
+    const rating = parseNumericSelector(query.rating);
+    if (rating) result.rating = rating;
+  }
+  if (query.votes) {
+    const votes = parseNumericSelector(query.votes);
+    if (votes) result.votes = votes;
+  }
+
+  return result;
+}

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

@@ -0,0 +1,106 @@
+/**
+ *
+ * Parser rule for the Wikidot `[[module ListPages ...]]` block.
+ *
+ * Parses the module's attributes into a structured `list-pages` Module AST node.
+ * Handles both hyphenated (`link-to`) and concatenated (`linkto`) attribute name
+ * formats, as Wikidot normalizes both to lowercase. The raw attribute values are
+ * preserved in the `attributes` field for `@URL` resolution by external applications.
+ *
+ * @module
+ */
+
+import type { Module } from "@wdprlib/ast";
+import type { ModuleRule } from "../types";
+import { parseBool, parseInt32 } from "../utils";
+
+/**
+ * Module rule for `[[module ListPages ...]]`.
+ *
+ * ListPages is the most complex Wikidot module. It queries pages by various
+ * criteria (tags, category, parent, date, rating, etc.) and renders each matching
+ * page using a template specified in the module body. The template uses
+ * `%%variable%%` syntax to reference page data.
+ *
+ * This rule only handles parsing; data fetching and template rendering are handled
+ * by the extract/resolve pipeline.
+ */
+export const listPagesModuleRule: ModuleRule = {
+  name: "module-listpages",
+  acceptsNames: ["listpages"],
+  hasBody: true,
+
+  parse(_ctx, _pos, args, body): Module {
+    // Extract known attributes, pass rest as additional attributes
+    // Note: attribute names are normalized to lowercase by parseAttributesRaw
+    const {
+      category,
+      tags,
+      parent,
+      rating,
+      votes,
+      name,
+      fullname,
+      range,
+      pagetype,
+      offset,
+      limit,
+      order,
+      reverse,
+      separate,
+      wrapper,
+      rss,
+    } = args;
+    // Hyphenated attributes (stored with hyphens in lowercase)
+    const linkTo = args["link-to"] ?? args.linkto;
+    const createdBy = args["created-by"] ?? args.createdby;
+    const createdAt = args["created-at"] ?? args.createdat;
+    const updatedAt = args["updated-at"] ?? args.updatedat;
+    const perPage = args["per-page"] ?? args.perpage;
+    const prependLine = args["prepend-line"] ?? args.prependline;
+    const appendLine = args["append-line"] ?? args.appendline;
+    const rssDescription = args["rss-description"] ?? args.rssdescription;
+    const rssHome = args["rss-home"] ?? args.rsshome;
+    const rssLimit = args["rss-limit"] ?? args.rsslimit;
+    const rssOnly = args["rss-only"] ?? args.rssonly;
+    const urlAttrPrefix = args["url-attr-prefix"] ?? args.urlattrprefix;
+
+    // Store all raw arguments for @URL resolution by external apps
+    const rawArgs: Record<string, string> = { ...args };
+
+    return {
+      module: "list-pages",
+      category,
+      tags,
+      parent,
+      "link-to": linkTo,
+      "created-by": createdBy,
+      "created-at": createdAt,
+      "updated-at": updatedAt,
+      rating,
+      votes,
+      name,
+      fullname,
+      range,
+      pagetype,
+      offset: parseInt32(offset),
+      limit: parseInt32(limit),
+      "per-page": parseInt32(perPage),
+      order,
+      reverse: parseBool(reverse, false),
+      separate: parseBool(separate, true),
+      wrapper: parseBool(wrapper, true),
+      "prepend-line": prependLine,
+      "append-line": appendLine,
+      rss,
+      "rss-description": rssDescription,
+      "rss-home": rssHome,
+      "rss-limit": parseInt32(rssLimit),
+      "rss-only": parseBool(rssOnly, false),
+      "url-attr-prefix": urlAttrPrefix,
+      body,
+      // All raw arguments for @URL resolution
+      attributes: rawArgs,
+    };
+  },
+};

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

@@ -0,0 +1,130 @@
+/**
+ *
+ * ListPages module resolution (phase 3 of the ListPages lifecycle).
+ *
+ * After the application has fetched page data based on the extracted requirements,
+ * this module substitutes that data into the pre-compiled templates and re-parses
+ * the resulting wikitext to produce final AST elements.
+ *
+ * For each page in the fetched data:
+ * 1. Build a `VariableContext` with page data, index, total count, and site info
+ * 2. Execute the compiled template to produce a wikitext string
+ * 3. Re-parse the wikitext string into AST elements
+ * 4. Optionally wrap each item in a `div.list-pages-item` (when `separate=true`)
+ *
+ * The final result may also include prepend/append lines and be wrapped in a
+ * `div.list-pages-box` (when `wrapper=true`).
+ *
+ * @module
+ */
+
+import type { Element, Module } from "@wdprlib/ast";
+import type { ListPagesExternalData, CompiledTemplate, VariableContext } from "./types";
+import type { ParseFunction } from "../types";
+export type { ParseFunction };
+
+/**
+ * Narrowed type for the list-pages variant of the Module discriminated union.
+ */
+export type ListPagesModuleData = Extract<Module, { module: "list-pages" }>;
+
+/**
+ * Type guard to check if a Module is a list-pages module.
+ *
+ * @param module - A Module discriminated union value
+ * @returns true if the module is a list-pages module
+ */
+export function isListPagesModule(module: Module): module is ListPagesModuleData {
+  return module.module === "list-pages";
+}
+
+/**
+ * Resolve a single ListPages module
+ *
+ * @param module - ListPages module data from AST
+ * @param data - External data fetched for this module
+ * @param compiledTemplate - Pre-compiled template function
+ * @param parse - Parser function for re-parsing templates
+ * @returns Resolved elements
+ */
+export function resolveListPages(
+  module: ListPagesModuleData,
+  data: ListPagesExternalData,
+  compiledTemplate: CompiledTemplate,
+  parse: ParseFunction,
+): Element[] {
+  const items: Element[] = [];
+
+  // Process each page
+  for (let i = 0; i < data.pages.length; i++) {
+    const page = data.pages[i];
+    if (!page) continue;
+
+    const ctx: VariableContext = {
+      page,
+      index: i + 1,
+      total: data.totalCount,
+      limit: module.limit,
+      site: data.site,
+    };
+
+    // Execute compiled template
+    const substituted = compiledTemplate(ctx);
+
+    // Re-parse as wikitext
+    const itemAst = parse(substituted);
+
+    if (module.separate) {
+      // Wrap each item in div
+      const wrapper: Element = {
+        element: "container",
+        data: {
+          type: "div",
+          attributes: { class: "list-pages-item" },
+          elements: itemAst.elements,
+        },
+      };
+      items.push(wrapper);
+    } else {
+      items.push(...itemAst.elements);
+    }
+  }
+
+  // Handle empty results
+  if (items.length === 0) {
+    return [];
+  }
+
+  // Build final result
+  const result: Element[] = [];
+
+  // Prepend line (only when separate=false)
+  if (module["prepend-line"] && !module.separate) {
+    const prependAst = parse(module["prepend-line"]);
+    result.push(...prependAst.elements);
+  }
+
+  result.push(...items);
+
+  // Append line (only when separate=false)
+  if (module["append-line"] && !module.separate) {
+    const appendAst = parse(module["append-line"]);
+    result.push(...appendAst.elements);
+  }
+
+  // Wrap everything if wrapper=true
+  if (module.wrapper) {
+    return [
+      {
+        element: "container",
+        data: {
+          type: "div",
+          attributes: { class: "list-pages-box" },
+          elements: result,
+        },
+      },
+    ];
+  }
+
+  return result;
+}