@wdprlib/parser 3.2.0 → 4.0.0

package/src/parser/rules/block/module/listpages/types/external-data.ts

@@ -0,0 +1,77 @@
+/**
+ * User information.
+ */
+export interface UserInfo {
+  id: number;
+  name: string;
+  unixName: string;
+}
+
+/**
+ * Page data provided by an external source.
+ */
+export interface PageData {
+  // Identity
+  name: string;
+  category: string;
+  fullname: string;
+  title: string;
+
+  // Lifecycle - created
+  createdAt: Date;
+  createdBy?: UserInfo;
+
+  // Lifecycle - updated
+  updatedAt: Date;
+  updatedBy?: UserInfo;
+
+  // Lifecycle - commented
+  commentedAt?: Date;
+  commentedBy?: UserInfo;
+
+  // Parent
+  parentName?: string;
+  parentCategory?: string;
+  parentFullname?: string;
+  parentTitle?: string;
+
+  // Wikitext content split by ==== when resolving %%content{n}%%.
+  content?: string;
+
+  // Tags
+  tags: string[];
+  hiddenTags: string[];
+
+  // Form data
+  formData?: Record<string, string>;
+  formRaw?: Record<string, string>;
+  formLabel?: Record<string, string>;
+  formHint?: Record<string, string>;
+
+  // Metrics
+  children: number;
+  comments: number;
+  size: number;
+  rating: number;
+  ratingVotes: number;
+  ratingPercent?: number;
+  revisions: number;
+}
+
+/**
+ * Site context information.
+ */
+export interface SiteContext {
+  title: string;
+  name: string;
+  domain: string;
+}
+
+/**
+ * External data for a single ListPages module.
+ */
+export interface ListPagesExternalData {
+  pages: PageData[];
+  totalCount: number;
+  site: SiteContext;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Public type facade for the ListPages module system.
+ *
+ * The actual declarations live under `listpages/types/` by lifecycle concern:
+ * query input, template variables, data requirements, external data, compiled
+ * templates, and normalized selectors.
+ *
+ * @module
+ */
+
+export type * from "./query";
+export type * from "./variables";
+export type * from "./data-requirements";
+export type * from "./external-data";
+export type * from "./data-fetcher";
+export type * from "./template";
+export type * from "./normalized-query";

package/src/parser/rules/block/module/listpages/types/normalized-query.ts

@@ -0,0 +1,120 @@
+/**
+ * Normalized tags selector.
+ */
+export interface NormalizedTags {
+  /** AND conditions - pages must have all of these tags (+tag). */
+  all: string[];
+  /** OR conditions - pages must have any of these tags (no prefix). */
+  any: string[];
+  /** NOT conditions - pages must not have these tags (-tag). */
+  none: string[];
+  /** Special selector. */
+  special: "same-visible" | "same-all" | "none" | null;
+}
+
+/**
+ * Normalized category selector.
+ */
+export interface NormalizedCategory {
+  /** Categories to include. */
+  include: string[];
+  /** Categories to exclude (-category). */
+  exclude: string[];
+  /** Select all categories (*). */
+  all: boolean;
+  /** Select current category (.). */
+  current: boolean;
+}
+
+/**
+ * Order field options.
+ */
+export type OrderField =
+  | "created_at"
+  | "updated_at"
+  | "title"
+  | "fullname"
+  | "rating"
+  | "votes"
+  | "revisions"
+  | "comments"
+  | "size"
+  | "random";
+
+/**
+ * Order direction.
+ */
+export type OrderDirection = "asc" | "desc";
+
+/**
+ * Normalized order specification.
+ */
+export interface NormalizedOrder {
+  field: OrderField;
+  direction: OrderDirection;
+}
+
+/**
+ * Normalized parent selector.
+ */
+export type NormalizedParent =
+  | { type: "none" }
+  | { type: "same" }
+  | { type: "different" }
+  | { type: "children" }
+  | { type: "page"; name: string };
+
+/**
+ * Date comparison operators.
+ */
+export type DateComparisonOp = "=" | "<" | ">" | "<=" | ">=" | "<>";
+
+/**
+ * Normalized date selector.
+ */
+export type NormalizedDateSelector =
+  | { type: "year"; year: number }
+  | { type: "month"; year: number; month: number }
+  | { type: "comparison"; op: DateComparisonOp; date: string }
+  | { type: "relative"; unit: "day" | "week" | "month"; count: number };
+
+/**
+ * Numeric comparison operators.
+ */
+export type NumericComparisonOp = "=" | "<" | ">" | "<=" | ">=";
+
+/**
+ * Normalized numeric selector for rating/votes.
+ */
+export interface NormalizedNumericSelector {
+  op: NumericComparisonOp;
+  value: number;
+}
+
+/**
+ * Fully normalized ListPages query.
+ *
+ * All string fields are parsed into structured selector objects. Use
+ * `normalizeQuery()` to convert from `ListPagesQuery`.
+ */
+export interface NormalizedListPagesQuery {
+  pagetype?: "normal" | "hidden" | "*";
+  category?: NormalizedCategory;
+  tags?: NormalizedTags;
+  parent?: NormalizedParent;
+  linkTo?: string;
+  createdAt?: NormalizedDateSelector;
+  updatedAt?: NormalizedDateSelector;
+  createdBy?: string;
+  rating?: NormalizedNumericSelector;
+  votes?: NormalizedNumericSelector;
+  name?: string;
+  fullname?: string;
+  range?: "." | "before" | "after" | "others";
+  dataFormFields?: Record<string, string>;
+  order?: NormalizedOrder;
+  offset?: number;
+  limit?: number;
+  perPage?: number;
+  reverse?: boolean;
+}

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

@@ -0,0 +1,67 @@
+/**
+ * ListPages query parameters for page selection.
+ *
+ * @security All string fields contain untrusted user input from wikitext.
+ * When using these values in database queries:
+ * - NEVER interpolate directly into SQL/NoSQL query strings.
+ * - ALWAYS use parameterized queries or prepared statements.
+ * - For ORDER BY clauses, use a whitelist of allowed column names.
+ */
+export interface ListPagesQuery {
+  /** Page type selector */
+  pagetype?: "normal" | "hidden" | "*";
+
+  /** Category selector. @untrusted User input - use parameterized queries. */
+  category?: string;
+
+  /** Tag selector, e.g. "+fruit -admin". @untrusted User input. */
+  tags?: string;
+
+  /** Parent page selector. @untrusted User input. */
+  parent?: string;
+
+  /** Link target selector. @untrusted User input. */
+  linkTo?: string;
+
+  /** Created date selector. @untrusted User input. */
+  createdAt?: string;
+
+  /** Updated date selector. @untrusted User input. */
+  updatedAt?: string;
+
+  /** Author selector. @untrusted User input. */
+  createdBy?: string;
+
+  /** Rating selector. @untrusted User input. */
+  rating?: string;
+
+  /** Votes selector. @untrusted User input. */
+  votes?: string;
+
+  /** Page name selector. @untrusted User input. */
+  name?: string;
+
+  /** Full page name selector (category:name). @untrusted User input. */
+  fullname?: string;
+
+  /** Range selector relative to current page */
+  range?: "." | "before" | "after" | "others";
+
+  /** Data form field selectors. @untrusted Both keys and values are user input. */
+  dataFormFields?: Record<string, string>;
+
+  /** Ordering specification. @untrusted Use whitelist validation for ORDER BY. */
+  order?: string;
+
+  /** Pagination offset */
+  offset?: number;
+
+  /** Maximum number of results */
+  limit?: number;
+
+  /** Results per page */
+  perPage?: number;
+
+  /** Reverse order */
+  reverse?: boolean;
+}

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

@@ -0,0 +1,17 @@
+import type { PageData, SiteContext } from "./external-data";
+
+/**
+ * Context passed to a compiled ListPages template.
+ */
+export interface VariableContext {
+  page: PageData;
+  index: number;
+  total: number;
+  limit?: number;
+  site: SiteContext;
+}
+
+/**
+ * Compiled template function.
+ */
+export type CompiledTemplate = (ctx: VariableContext) => string;

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

@@ -0,0 +1,69 @@
+/**
+ * All supported ListPages template variables.
+ */
+export type ListPagesVariable =
+  // Lifecycle - created
+  | "created_at"
+  | "created_by"
+  | "created_by_unix"
+  | "created_by_id"
+  | "created_by_linked"
+  // Lifecycle - updated
+  | "updated_at"
+  | "updated_by"
+  | "updated_by_unix"
+  | "updated_by_id"
+  | "updated_by_linked"
+  // Lifecycle - commented
+  | "commented_at"
+  | "commented_by"
+  | "commented_by_unix"
+  | "commented_by_id"
+  | "commented_by_linked"
+  // Structure - page
+  | "name"
+  | "category"
+  | "fullname"
+  | "title"
+  | "title_linked"
+  | "link"
+  // Structure - parent
+  | "parent_name"
+  | "parent_category"
+  | "parent_fullname"
+  | "parent_title"
+  | "parent_title_linked"
+  // Content
+  | "content"
+  | "content_n"
+  | "preview"
+  | "preview_n"
+  | "summary"
+  | "first_paragraph"
+  // Tags
+  | "tags"
+  | "tags_linked"
+  | "_tags"
+  | "_tags_linked"
+  // Form data
+  | "form_data"
+  | "form_raw"
+  | "form_label"
+  | "form_hint"
+  // Metrics
+  | "children"
+  | "comments"
+  | "size"
+  | "rating"
+  | "rating_votes"
+  | "rating_percent"
+  | "revisions"
+  // Pagination
+  | "index"
+  | "total"
+  | "limit"
+  | "total_or_limit"
+  // Site context
+  | "site_title"
+  | "site_name"
+  | "site_domain";

package/src/parser/rules/block/module/listpages/url-resolution/fields.ts

@@ -0,0 +1,48 @@
+import type { ListPagesQuery } from "../types";
+
+export type UrlResolvableField =
+  | { attr: string; queryKey: StringUrlQueryKey; type: "string" }
+  | { attr: string; queryKey: NumberUrlQueryKey; type: "number" }
+  | { attr: string; queryKey: BooleanUrlQueryKey; type: "boolean" };
+
+type StringUrlQueryKey = Extract<
+  keyof ListPagesQuery,
+  | "order"
+  | "tags"
+  | "category"
+  | "parent"
+  | "range"
+  | "name"
+  | "fullname"
+  | "createdAt"
+  | "updatedAt"
+  | "createdBy"
+  | "rating"
+  | "votes"
+>;
+
+type NumberUrlQueryKey = Extract<keyof ListPagesQuery, "offset" | "limit" | "perPage">;
+type BooleanUrlQueryKey = Extract<keyof ListPagesQuery, "reverse">;
+
+/**
+ * Mapping of module attribute names to their corresponding `ListPagesQuery` keys
+ * and expected value types. Only fields listed here support `@URL` resolution.
+ */
+export const URL_RESOLVABLE_FIELDS: readonly UrlResolvableField[] = [
+  { attr: "offset", queryKey: "offset", type: "number" },
+  { attr: "limit", queryKey: "limit", type: "number" },
+  { attr: "per-page", queryKey: "perPage", type: "number" },
+  { attr: "order", queryKey: "order", type: "string" },
+  { attr: "tags", queryKey: "tags", type: "string" },
+  { attr: "category", queryKey: "category", type: "string" },
+  { attr: "parent", queryKey: "parent", type: "string" },
+  { attr: "range", queryKey: "range", type: "string" },
+  { attr: "name", queryKey: "name", type: "string" },
+  { attr: "fullname", queryKey: "fullname", type: "string" },
+  { attr: "created-at", queryKey: "createdAt", type: "string" },
+  { attr: "updated-at", queryKey: "updatedAt", type: "string" },
+  { attr: "created-by", queryKey: "createdBy", type: "string" },
+  { attr: "rating", queryKey: "rating", type: "string" },
+  { attr: "votes", queryKey: "votes", type: "string" },
+  { attr: "reverse", queryKey: "reverse", type: "boolean" },
+];

package/src/parser/rules/block/module/listpages/url-resolution/params.ts

@@ -0,0 +1,19 @@
+/**
+ * Parse URL path parameters like /offset/1/page2_limit/1.
+ * Returns a map of parameter name -> value.
+ */
+export function parseUrlParams(url: string): Map<string, string> {
+  const params = new Map<string, string>();
+  const parts = url.split("/").filter(Boolean);
+
+  // Skip the page name (first part), parse key/value pairs.
+  for (let i = 1; i < parts.length - 1; i += 2) {
+    const key = parts[i];
+    const value = parts[i + 1];
+    if (key && value) {
+      params.set(key, value);
+    }
+  }
+
+  return params;
+}

package/src/parser/rules/block/module/listpages/url-resolution/query.ts

@@ -0,0 +1,24 @@
+import type { ListPagesQuery } from "../types";
+import type { UrlResolvableField } from "./fields";
+
+export function assignResolvedUrlField(
+  query: ListPagesQuery,
+  field: UrlResolvableField,
+  value: string,
+): void {
+  switch (field.type) {
+    case "number": {
+      const num = parseInt(value, 10);
+      if (!Number.isNaN(num)) {
+        query[field.queryKey] = num;
+      }
+      return;
+    }
+    case "boolean":
+      query[field.queryKey] = value === "true" || value === "yes" || value === "1";
+      return;
+    case "string":
+      Object.assign(query, { [field.queryKey]: value });
+      return;
+  }
+}

package/src/parser/rules/block/module/listpages/url-resolution/resolve.ts

@@ -0,0 +1,53 @@
+import type { ListPagesDataRequirement, ListPagesQuery, NormalizedListPagesQuery } from "../types";
+import { normalizeQuery } from "../normalize";
+import { URL_RESOLVABLE_FIELDS } from "./fields";
+import { assignResolvedUrlField } from "./query";
+import { resolveUrlValue } from "./value";
+
+/**
+ * Resolve all `@URL` parameters and build a ListPagesQuery.
+ *
+ * Takes a ListPagesDataRequirement and URL parameters, resolves all `@URL|default`
+ * values, and returns a complete ListPagesQuery ready for database queries.
+ *
+ * @param requirement - The data requirement from AST extraction
+ * @param urlParams - Parsed URL parameters (from parseUrlParams)
+ * @returns Resolved ListPagesQuery
+ */
+export function resolveQuery(
+  requirement: ListPagesDataRequirement,
+  urlParams: Map<string, string>,
+): ListPagesQuery {
+  const { query, rawAttributes, urlAttrPrefix } = requirement;
+  const resolved: ListPagesQuery = { ...query };
+
+  for (const field of URL_RESOLVABLE_FIELDS) {
+    const rawValue = rawAttributes[field.attr];
+    if (!rawValue) continue;
+
+    const resolvedValue = resolveUrlValue(rawValue, field.attr, urlParams, urlAttrPrefix);
+    if (resolvedValue === undefined) continue;
+
+    assignResolvedUrlField(resolved, field, resolvedValue);
+  }
+
+  return resolved;
+}
+
+/**
+ * Resolve all `@URL` parameters and normalize the query.
+ *
+ * Combines URL resolution with query normalization in a single call.
+ * This is the recommended way to process ListPages queries for HPC.
+ *
+ * @param requirement - The data requirement from AST extraction
+ * @param urlParams - Parsed URL parameters (from parseUrlParams)
+ * @returns Normalized query with all `@URL` values resolved
+ */
+export function resolveAndNormalizeQuery(
+  requirement: ListPagesDataRequirement,
+  urlParams: Map<string, string>,
+): NormalizedListPagesQuery {
+  const resolved = resolveQuery(requirement, urlParams);
+  return normalizeQuery(resolved);
+}

package/src/parser/rules/block/module/listpages/url-resolution/value.ts

@@ -0,0 +1,25 @@
+/**
+ * Resolve @URL|default format with actual URL parameters.
+ *
+ * @param rawValue - The raw attribute value (e.g., "@URL|0")
+ * @param paramName - The parameter name (e.g., "offset")
+ * @param urlParams - Parsed URL parameters
+ * @param prefix - Optional URL attribute prefix (e.g., "page2")
+ * @returns Resolved value
+ */
+export function resolveUrlValue(
+  rawValue: string | undefined,
+  paramName: string,
+  urlParams: Map<string, string>,
+  prefix?: string,
+): string | undefined {
+  if (!rawValue) return undefined;
+
+  if (!rawValue.startsWith("@URL")) {
+    return rawValue;
+  }
+
+  const defaultValue = rawValue.includes("|") ? rawValue.split("|")[1] : undefined;
+  const actualParamName = prefix ? `${prefix}_${paramName}` : paramName;
+  return urlParams.get(actualParamName) ?? defaultValue;
+}