@wdprlib/parser 3.1.2 → 3.2.0

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

@@ -0,0 +1,513 @@
+/**
+ *
+ * Type definitions for the ListPages module system.
+ *
+ * This file defines the complete type vocabulary for the ListPages lifecycle:
+ *
+ * - **Query types**: Raw and normalized representations of ListPages filter/sort parameters
+ * - **Variable types**: The `%%variable%%` names supported in ListPages templates
+ * - **Data requirement types**: What the parser tells the application it needs to fetch
+ * - **External data types**: What the application provides back (page data, user info, site context)
+ * - **Template types**: Compiled template function signatures and their execution context
+ * - **Normalized query types**: Structured representations of parsed query parameters
+ *
+ * Security note: Several fields contain untrusted user input from wikitext.
+ * See `ListPagesQuery` documentation for safe usage guidelines.
+ *
+ * @module
+ */
+
+// =============================================================================
+// Query Types
+// =============================================================================
+
+/**
+ * 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
+ *
+ * @example Safe usage with SQL
+ * ```typescript
+ * // GOOD: Parameterized query
+ * db.query("SELECT * FROM pages WHERE category = ?", [query.category]);
+ *
+ * // BAD: String interpolation (SQL injection vulnerable!)
+ * db.query(`SELECT * FROM pages WHERE category = '${query.category}'`);
+ * ```
+ */
+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 - use parameterized queries
+   */
+  tags?: string;
+
+  /**
+   * Parent page selector
+   * @untrusted User input - use parameterized queries
+   */
+  parent?: string;
+
+  /**
+   * Link target selector
+   * @untrusted User input - use parameterized queries
+   */
+  linkTo?: string;
+
+  /**
+   * Created date selector
+   * @untrusted User input - use parameterized queries
+   */
+  createdAt?: string;
+
+  /**
+   * Updated date selector
+   * @untrusted User input - use parameterized queries
+   */
+  updatedAt?: string;
+
+  /**
+   * Author selector
+   * @untrusted User input - use parameterized queries
+   */
+  createdBy?: string;
+
+  /**
+   * Rating selector
+   * @untrusted User input - use parameterized queries
+   */
+  rating?: string;
+
+  /**
+   * Votes selector
+   * @untrusted User input - use parameterized queries
+   */
+  votes?: string;
+
+  /**
+   * Page name selector
+   * @untrusted User input - use parameterized queries
+   */
+  name?: string;
+
+  /**
+   * Full page name selector (category:name)
+   * @untrusted User input - use parameterized queries
+   */
+  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 User input - 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;
+}
+
+// =============================================================================
+// Variable Types
+// =============================================================================
+
+/**
+ * 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" // content{n}
+  | "preview"
+  | "preview_n" // 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";
+
+// =============================================================================
+// Data Requirement Types
+// =============================================================================
+
+/**
+ * Data requirement for a single ListPages module
+ */
+export interface ListPagesDataRequirement {
+  /** Unique identifier for this module instance */
+  id: number;
+
+  /** Query parameters */
+  query: ListPagesQuery;
+
+  /** Variables used in the template */
+  neededVariables: ListPagesVariable[];
+
+  /** Indices needed for content{n} */
+  contentSectionIndices?: number[];
+
+  /** Lengths needed for preview(n) */
+  previewLengths?: number[];
+
+  /** Field names needed for form_data{field} etc */
+  formFields?: string[];
+
+  /** Prefix for tags_linked|prefix */
+  tagsLinkPrefix?: string;
+
+  /** Prefix for _tags_linked|prefix */
+  hiddenTagsLinkPrefix?: string;
+
+  /**
+   * URL attribute prefix for multiple ListPages modules
+   * When set, URL parameters are prefixed (e.g., "page2" -> "/page2_limit/1")
+   */
+  urlAttrPrefix?: string;
+
+  /**
+   * Raw attribute values before URL resolution
+   * Contains original string values that may include "@URL" or "@URL|default" format
+   * External applications should use these to resolve URL parameters
+   */
+  rawAttributes: Record<string, string>;
+}
+
+/**
+ * All data requirements from parsing
+ */
+export interface DataRequirements {
+  listPages: ListPagesDataRequirement[];
+  listUsers: import("../listusers/types").ListUsersDataRequirement[];
+}
+
+// =============================================================================
+// External Data Types
+// =============================================================================
+
+/**
+ * User information
+ */
+export interface UserInfo {
+  id: number;
+  name: string;
+  unixName: string;
+}
+
+/**
+ * Page data provided by 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;
+
+  // Content (====で区切られた形式。wdparserが%%content{n}%%解決時に分割する)
+  content?: string;
+
+  // Tags
+  tags: string[];
+  hiddenTags: string[]; // Starting with _
+
+  // 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;
+}
+
+/**
+ * Callback to fetch data for a ListPages module
+ *
+ * Called by resolveModules for each ListPages module in the AST.
+ * Receives a normalized query with all `@URL` parameters resolved.
+ * Return null/undefined to skip the module (outputs nothing).
+ *
+ * @param query - Normalized query with structured types (tags, category, order, etc.)
+ * @param requirement - Original data requirement (for accessing id, neededVariables, etc.)
+ */
+export type ListPagesDataFetcher = (
+  query: NormalizedListPagesQuery,
+  requirement: ListPagesDataRequirement,
+) => ListPagesExternalData | null | undefined | Promise<ListPagesExternalData | null | undefined>;
+
+// Note: DataProvider is in ../types-common.ts to avoid circular dependency
+
+// =============================================================================
+// Compiled Template Types
+// =============================================================================
+
+/**
+ * Context passed to compiled template
+ */
+export interface VariableContext {
+  page: PageData;
+  index: number;
+  total: number;
+  limit?: number;
+  site: SiteContext;
+}
+
+/**
+ * Compiled template function
+ */
+export type CompiledTemplate = (ctx: VariableContext) => string;
+
+// =============================================================================
+// Normalized Query Types
+// =============================================================================
+
+/**
+ * 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" } // "-": orphan pages
+  | { type: "same" } // "=": sibling pages
+  | { type: "different" } // "-=": different parent
+  | { type: "children" } // ".": children of current page
+  | { type: "page"; name: string }; // specific page name
+
+/**
+ * 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 and structured into type-safe objects.
+ * Use `normalizeQuery()` to convert from `ListPagesQuery`.
+ *
+ * Note: This is structural normalization, not full validation.
+ * Invalid inputs are either rejected (return undefined) or ignored.
+ */
+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/url-resolver.ts

@@ -0,0 +1,186 @@
+/**
+ *
+ * URL parameter resolver for the `@URL|default` format in ListPages modules.
+ *
+ * Wikidot's ListPages module supports a dynamic parameter syntax where attribute
+ * values can be set to `@URL` or `@URL|default`. At render time, the actual value
+ * is read from the page's URL path parameters. This enables "HPC" (Hyper Page
+ * Changer) style multi-page content where a single page definition can display
+ * different data based on URL parameters.
+ *
+ * URL parameters follow the pattern `/key/value/key/value/...` in the URL path.
+ * When a `url-attr-prefix` is set (e.g., `"page2"`), parameter names are prefixed
+ * (e.g., `page2_offset`, `page2_limit`), allowing multiple independent ListPages
+ * modules on the same page.
+ *
+ * @example
+ * Wikidot markup:
+ * ```
+ * [[module ListPages offset="@URL|0" limit="@URL|10" url-attr-prefix="p2"]]
+ * ```
+ * URL: `/my-page/p2_offset/20/p2_limit/5`
+ * Result: offset=20, limit=5
+ *
+ * @module
+ */
+
+import type { ListPagesDataRequirement, ListPagesQuery, NormalizedListPagesQuery } from "./types";
+import { normalizeQuery } from "./normalize";
+
+/**
+ * Mapping of module attribute names to their corresponding `ListPagesQuery` keys
+ * and expected value types. Only fields listed here support `@URL` resolution.
+ */
+const URL_RESOLVABLE_FIELDS: ReadonlyArray<{
+  attr: string;
+  queryKey: keyof ListPagesQuery;
+  type: "string" | "number" | "boolean";
+}> = [
+  { 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" },
+];
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+
+  // Check for @URL or @URL|default format
+  if (!rawValue.startsWith("@URL")) {
+    return rawValue;
+  }
+
+  // Extract default value if present
+  const defaultValue = rawValue.includes("|") ? rawValue.split("|")[1] : undefined;
+
+  // Build the actual parameter name with prefix
+  const actualParamName = prefix ? `${prefix}_${paramName}` : paramName;
+
+  // Get from URL params or use default
+  return urlParams.get(actualParamName) ?? defaultValue;
+}
+
+/**
+ * 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
+ *
+ * @example
+ * ```typescript
+ * const urlParams = parseUrlParams("/page/scp-001/page2_offset/10/page2_limit/5");
+ * const query = resolveQuery(requirement, urlParams);
+ * // query.offset = 10, query.limit = 5 (if urlAttrPrefix = "page2")
+ * ```
+ */
+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;
+
+    // Convert to appropriate type
+    switch (field.type) {
+      case "number": {
+        const num = parseInt(resolvedValue, 10);
+        if (!Number.isNaN(num)) {
+          (resolved as Record<string, unknown>)[field.queryKey] = num;
+        }
+        break;
+      }
+      case "boolean":
+        (resolved as Record<string, unknown>)[field.queryKey] =
+          resolvedValue === "true" || resolvedValue === "yes" || resolvedValue === "1";
+        break;
+      case "string":
+      default:
+        (resolved as Record<string, unknown>)[field.queryKey] = resolvedValue;
+        break;
+    }
+  }
+
+  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
+ *
+ * @example
+ * ```typescript
+ * const urlParams = parseUrlParams(window.location.pathname);
+ * const normalizedQuery = resolveAndNormalizeQuery(requirement, urlParams);
+ * // Ready for database query building
+ * ```
+ */
+export function resolveAndNormalizeQuery(
+  requirement: ListPagesDataRequirement,
+  urlParams: Map<string, string>,
+): NormalizedListPagesQuery {
+  const resolved = resolveQuery(requirement, urlParams);
+  return normalizeQuery(resolved);
+}