@wdprlib/parser 4.2.0 → 4.4.0

package/src/parser/rules/block/module/resolution/document.ts

@@ -0,0 +1,357 @@
+import {
+  evaluateExpression,
+  isTruthy,
+  type Diagnostic,
+  type Element,
+  type ParseResult,
+  type SyntaxTree,
+  type TocEntry,
+} from "@wdprlib/ast";
+import { extractHeadingText } from "../../heading/toc-text";
+import { buildTableOfContents } from "../../../../toc";
+import { resolveIfTags } from "../iftags/resolve";
+import {
+  getGenericElementChildren,
+  listElement,
+  withGenericElementChildren,
+} from "../walk/children";
+import type { ModuleParseResult } from "../types";
+
+interface RegisterOptions {
+  stripLegacyImplicitFootnoteBlock?: boolean;
+}
+
+/** Tracks parse-local side channels while module fragments are merged. */
+export class ModuleDocumentRegistry {
+  private readonly footnotesByElement = new WeakMap<Element, Element[]>();
+  readonly diagnostics: Diagnostic[] = [];
+
+  register(result: ModuleParseResult, options: RegisterOptions = {}): SyntaxTree {
+    const parseResult = isParseResult(result) ? result : null;
+    const ast: SyntaxTree = parseResult ? parseResult.ast : (result as SyntaxTree);
+    const elements = options.stripLegacyImplicitFootnoteBlock
+      ? stripTrailingDefaultFootnoteBlock(ast.elements)
+      : ast.elements;
+    const registeredAst = elements === ast.elements ? ast : { ...ast, elements };
+
+    if (parseResult) {
+      this.diagnostics.push(...parseResult.diagnostics);
+    }
+    this.registerFootnotes(registeredAst);
+    return registeredAst;
+  }
+
+  finalize(
+    ast: SyntaxTree,
+    elements: Element[],
+    pageTags: string[] | null,
+    ensureFootnoteBlock = true,
+  ): SyntaxTree {
+    const normalizedElements = normalizeFootnoteBlocks(elements, ensureFootnoteBlock);
+    const footnotes: Element[][] = [];
+    const htmlBlocks: string[] = [];
+    const codeBlocks: NonNullable<SyntaxTree["code-blocks"]> = [];
+    const tocEntries: TocEntry[] = [];
+
+    const collectElement = (element: Element): void => {
+      if (element.element === "footnote") {
+        const content = this.footnotesByElement.get(element);
+        if (content) footnotes.push(content);
+      } else if (element.element === "html") {
+        htmlBlocks.push(element.data.contents);
+      } else if (element.element === "code") {
+        codeBlocks.push(element.data);
+      } else if (isTocHeading(element)) {
+        tocEntries.push({
+          level: element.data.type.header.level,
+          text: extractHeadingText(element.data.elements),
+        });
+      }
+    };
+    walkRenderOrder(normalizedElements, pageTags, collectElement);
+
+    const result: SyntaxTree = { ...ast, elements: normalizedElements };
+    setOptionalArray(result, "footnotes", footnotes);
+    setOptionalArray(result, "html-blocks", htmlBlocks);
+    setOptionalArray(result, "code-blocks", codeBlocks);
+    setOptionalArray(result, "table-of-contents", buildTableOfContents(tocEntries));
+    return result;
+  }
+
+  private registerFootnotes(ast: SyntaxTree): void {
+    const footnoteElements: Element[] = [];
+    walkSyntaxOrder(ast.elements, (element) => {
+      if (element.element === "footnote") footnoteElements.push(element);
+    });
+
+    for (let i = 0; i < footnoteElements.length; i++) {
+      const content = ast.footnotes?.[i];
+      if (content) this.footnotesByElement.set(footnoteElements[i]!, content);
+    }
+  }
+}
+
+function isParseResult(result: ModuleParseResult): result is ParseResult {
+  return "ast" in result && "diagnostics" in result;
+}
+
+function setOptionalArray<K extends keyof SyntaxTree>(
+  tree: SyntaxTree,
+  key: K,
+  value: NonNullable<SyntaxTree[K]>,
+): void {
+  if ((value as unknown[]).length > 0) {
+    tree[key] = value;
+  } else {
+    delete tree[key];
+  }
+}
+
+function stripTrailingDefaultFootnoteBlock(elements: Element[]): Element[] {
+  const last = elements.at(-1);
+  if (last?.element !== "footnote-block" || last.data.title !== null || last.data.hide === true) {
+    return elements;
+  }
+  return elements.slice(0, -1);
+}
+
+function normalizeFootnoteBlocks(elements: Element[], ensureFootnoteBlock: boolean): Element[] {
+  const state = { found: false };
+  const normalized = mapSyntaxElements(elements, (element) => {
+    if (element.element !== "footnote-block") return element;
+    if (state.found) return null;
+    state.found = true;
+    return element;
+  });
+
+  if (!state.found && ensureFootnoteBlock) {
+    normalized.push({
+      element: "footnote-block",
+      data: { title: null, hide: false },
+    });
+  }
+  return normalized;
+}
+
+export function containsSyntaxFootnoteBlock(elements: Element[]): boolean {
+  let found = false;
+  walkSyntaxOrder(elements, (element) => {
+    if (element.element === "footnote-block") found = true;
+  });
+  return found;
+}
+
+function mapSyntaxElements(
+  elements: Element[],
+  transform: (element: Element) => Element | null,
+): Element[] {
+  const result: Element[] = [];
+  for (const original of elements) {
+    const element = transform(original);
+    if (!element) continue;
+    result.push(mapSyntaxChildren(element, (children) => mapSyntaxElements(children, transform)));
+  }
+  return result;
+}
+
+function mapSyntaxChildren(
+  element: Element,
+  transform: (elements: Element[]) => Element[],
+): Element {
+  if (element.element === "if") {
+    return {
+      ...element,
+      data: {
+        ...element.data,
+        // oxlint-disable-next-line unicorn/no-thenable -- `then` is part of the public AST schema
+        then: transform(element.data.then),
+        else: transform(element.data.else),
+      },
+    };
+  }
+  if (element.element === "ifexpr") {
+    return {
+      ...element,
+      data: {
+        ...element.data,
+        // oxlint-disable-next-line unicorn/no-thenable -- `then` is part of the public AST schema
+        then: transform(element.data.then),
+        else: transform(element.data.else),
+      },
+    };
+  }
+  if (element.element === "bibliography-block") {
+    return {
+      ...element,
+      data: {
+        ...element.data,
+        entries: element.data.entries.map((entry) => ({
+          ...entry,
+          key: transform(entry.key),
+          value: transform(entry.value),
+        })),
+      },
+    };
+  }
+  if (element.element === "list") {
+    return {
+      ...element,
+      data: {
+        ...element.data,
+        items: element.data.items.map((item) =>
+          item["item-type"] === "elements"
+            ? { ...item, elements: transform(item.elements) }
+            : mapSubList(item, transform),
+        ),
+      },
+    };
+  }
+  if (element.element === "table") {
+    return {
+      ...element,
+      data: {
+        ...element.data,
+        rows: element.data.rows.map((row) => ({
+          ...row,
+          cells: row.cells.map((cell) => ({ ...cell, elements: transform(cell.elements) })),
+        })),
+      },
+    };
+  }
+  if (element.element === "definition-list") {
+    return {
+      ...element,
+      data: element.data.map((entry) => ({
+        ...entry,
+        key: transform(entry.key),
+        value: transform(entry.value),
+      })),
+    };
+  }
+  if (element.element === "tab-view") {
+    return {
+      ...element,
+      data: element.data.map((tab) => ({ ...tab, elements: transform(tab.elements) })),
+    };
+  }
+
+  const children = getGenericElementChildren(element);
+  return children === null ? element : withGenericElementChildren(element, transform(children));
+}
+
+function mapSubList(
+  item: Extract<ElementOfListItem, { "item-type": "sub-list" }>,
+  transform: (elements: Element[]) => Element[],
+): ElementOfListItem {
+  const transformed = transform([listElement(item.data)])[0];
+  return transformed?.element === "list" ? { ...item, data: transformed.data } : item;
+}
+
+type ElementOfListItem = Extract<Element, { element: "list" }>["data"]["items"][number];
+
+function walkSyntaxOrder(elements: Element[], callback: (element: Element) => void): void {
+  for (const element of elements) {
+    callback(element);
+    walkAllSyntaxChildren(element, (children) => walkSyntaxOrder(children, callback));
+  }
+}
+
+function walkRenderOrder(
+  elements: Element[],
+  pageTags: string[] | null,
+  callback: (element: Element) => void,
+): void {
+  for (const element of elements) {
+    callback(element);
+    if (element.element === "if") {
+      walkRenderOrder(
+        isTruthy(element.data.condition) ? element.data.then : element.data.else,
+        pageTags,
+        callback,
+      );
+      continue;
+    }
+    if (element.element === "ifexpr") {
+      const evaluated = evaluateExpression(element.data.expression);
+      if (evaluated.success) {
+        walkRenderOrder(
+          evaluated.value !== 0 ? element.data.then : element.data.else,
+          pageTags,
+          callback,
+        );
+      }
+      continue;
+    }
+    if (element.element === "if-tags") {
+      const resolved = resolveIfTags(element.data, pageTags);
+      if (!resolved.evaluated || resolved.matched) {
+        walkRenderOrder(element.data.elements, pageTags, callback);
+      }
+      continue;
+    }
+    if (element.element === "bibliography-block") {
+      if (!element.data.hide) {
+        for (const entry of element.data.entries) {
+          walkRenderOrder(entry.value, pageTags, callback);
+        }
+      }
+      continue;
+    }
+    walkBasicChildren(element, (children) => walkRenderOrder(children, pageTags, callback));
+  }
+}
+
+function walkAllSyntaxChildren(element: Element, callback: (elements: Element[]) => void): void {
+  if (element.element === "if" || element.element === "ifexpr") {
+    callback(element.data.then);
+    callback(element.data.else);
+    return;
+  }
+  if (element.element === "bibliography-block") {
+    for (const entry of element.data.entries) {
+      callback(entry.key);
+      callback(entry.value);
+    }
+    return;
+  }
+  walkBasicChildren(element, callback);
+}
+
+function walkBasicChildren(element: Element, callback: (elements: Element[]) => void): void {
+  if (element.element === "list") {
+    for (const item of element.data.items) {
+      callback(item["item-type"] === "elements" ? item.elements : [listElement(item.data)]);
+    }
+    return;
+  }
+  if (element.element === "table") {
+    for (const row of element.data.rows) {
+      for (const cell of row.cells) callback(cell.elements);
+    }
+    return;
+  }
+  if (element.element === "definition-list") {
+    for (const entry of element.data) {
+      callback(entry.key);
+      callback(entry.value);
+    }
+    return;
+  }
+  if (element.element === "tab-view") {
+    for (const tab of element.data) callback(tab.elements);
+    return;
+  }
+  const children = getGenericElementChildren(element);
+  if (children !== null) callback(children);
+}
+
+function isTocHeading(element: Element): element is Extract<Element, { element: "container" }> & {
+  data: { type: { header: { level: number; "has-toc": true } } };
+} {
+  return (
+    element.element === "container" &&
+    typeof element.data.type === "object" &&
+    "header" in element.data.type &&
+    element.data.type.header["has-toc"]
+  );
+}

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

@@ -0,0 +1,269 @@
+import type { Diagnostic, Element, ParseResult, SyntaxTree } from "@wdprlib/ast";
+import type { DataProvider } from "../types-common";
+import type { ModuleParseResult } from "../types";
+import { isListPagesModule, type ListPagesModuleData } from "../listpages/resolve";
+import type {
+  CompiledTemplate,
+  ListPagesDataRequirement,
+  ListPagesExternalData,
+  VariableContext,
+} from "../listpages/types";
+import { isListUsersModule } from "../listusers/resolve";
+import type {
+  ListUsersCompiledTemplate,
+  ListUsersDataRequirement,
+  ListUsersExternalData,
+  ListUsersVariableContext,
+} from "../listusers/types";
+import { isTagCloudModule, resolveTagCloud } from "../tagcloud/resolve";
+import type { TagCloudDataRequirement } from "../tagcloud/types";
+import { resolveIfTags } from "../iftags/resolve";
+import {
+  getGenericElementChildren,
+  listElement,
+  withGenericElementChildren,
+} from "../walk/children";
+import { buildListPagesDataMap, buildListUsersDataMap, buildTagCloudDataMap } from "./data-maps";
+import { ModuleDocumentRegistry } from "./document";
+import { collectStyles, mergeCollectedStyles } from "./styles";
+
+export type AsyncModuleParseFunction = (source: string) => Promise<ModuleParseResult>;
+
+export interface ResolveModulesWithAsyncParseOptions {
+  parse: AsyncModuleParseFunction;
+  compiledListPagesTemplates: Map<number, CompiledTemplate>;
+  compiledListUsersTemplates?: Map<number, ListUsersCompiledTemplate>;
+  requirements: {
+    listPages?: ListPagesDataRequirement[];
+    listUsers?: ListUsersDataRequirement[];
+    tagCloud?: TagCloudDataRequirement[];
+  };
+  urlPath?: string;
+  pageTags: string[];
+}
+
+export interface AsyncModuleResolutionResult {
+  ast: SyntaxTree;
+  diagnostics: Diagnostic[];
+}
+
+interface ResolutionState {
+  listPagesId: number;
+  listUsersId: number;
+  tagCloudId: number;
+}
+
+interface ResolutionContext {
+  dataProvider: DataProvider;
+  listPagesData: Map<number, ListPagesExternalData>;
+  listUsersData: Map<number, ListUsersExternalData>;
+  tagCloudData: Awaited<ReturnType<typeof buildTagCloudDataMap>>;
+  options: ResolveModulesWithAsyncParseOptions;
+  parse: (source: string) => Promise<SyntaxTree>;
+}
+
+export async function resolveModulesWithAsyncParse(
+  ast: SyntaxTree,
+  dataProvider: DataProvider,
+  options: ResolveModulesWithAsyncParseOptions,
+): Promise<AsyncModuleResolutionResult> {
+  const registry = new ModuleDocumentRegistry();
+  registry.register(ast);
+  const parse = async (source: string): Promise<SyntaxTree> =>
+    registry.register(await options.parse(source));
+
+  const [listPagesData, listUsersData, tagCloudData] = await Promise.all([
+    buildListPagesDataMap(dataProvider, options.requirements.listPages ?? [], options.urlPath),
+    buildListUsersDataMap(dataProvider, options.requirements.listUsers ?? []),
+    buildTagCloudDataMap(dataProvider, options.requirements.tagCloud ?? []),
+  ]);
+  const context: ResolutionContext = {
+    dataProvider,
+    listPagesData,
+    listUsersData,
+    tagCloudData,
+    options,
+    parse,
+  };
+  const state: ResolutionState = { listPagesId: 0, listUsersId: 0, tagCloudId: 0 };
+  const resolvedElements = await resolveElements(ast.elements, context, state);
+  const { elements, styles, anchoredStyles } = collectStyles(resolvedElements);
+  const intermediate: SyntaxTree = { ...ast, elements };
+  const mergedStyles = mergeCollectedStyles(ast.styles, styles, new Map(), anchoredStyles);
+  if (mergedStyles.length > 0) intermediate.styles = mergedStyles;
+  else delete intermediate.styles;
+
+  return {
+    ast: registry.finalize(intermediate, elements, options.pageTags),
+    diagnostics: registry.diagnostics,
+  };
+}
+
+async function resolveElements(
+  elements: Element[],
+  context: ResolutionContext,
+  state: ResolutionState,
+): Promise<Element[]> {
+  const result: Element[] = [];
+  for (const element of elements) {
+    if (element.element === "module") {
+      const resolved = await resolveModuleElement(element, context, state);
+      if (resolved !== null) {
+        result.push(...resolved);
+        continue;
+      }
+    }
+
+    if (element.element === "if-tags") {
+      const resolution = resolveIfTags(element.data, context.options.pageTags);
+      if (resolution.matched) {
+        result.push(...(await resolveElements(element.data.elements, context, state)));
+      }
+      continue;
+    }
+
+    result.push(await resolveElementChildren(element, context, state));
+  }
+  return result;
+}
+
+async function resolveModuleElement(
+  element: Extract<Element, { element: "module" }>,
+  context: ResolutionContext,
+  state: ResolutionState,
+): Promise<Element[] | null> {
+  if (isListPagesModule(element.data)) {
+    const id = state.listPagesId++;
+    const data = context.listPagesData.get(id);
+    const template = context.options.compiledListPagesTemplates.get(id);
+    if (data && template) return resolveListPagesAsync(element.data, data, template, context.parse);
+    return context.dataProvider.fetchListPages ? [] : [element];
+  }
+  if (isListUsersModule(element.data)) {
+    const id = state.listUsersId++;
+    const data = context.listUsersData.get(id);
+    const template = context.options.compiledListUsersTemplates?.get(id);
+    if (data && template) {
+      const variableContext: ListUsersVariableContext = { user: data.user };
+      return (await context.parse(template(variableContext))).elements;
+    }
+    return context.dataProvider.fetchListUsers ? [] : [element];
+  }
+  if (isTagCloudModule(element.data)) {
+    const id = state.tagCloudId++;
+    const data = context.tagCloudData.get(id);
+    if (data) return resolveTagCloud(element.data, data);
+    return context.dataProvider.fetchTagCloud ? [] : [element];
+  }
+  return null;
+}
+
+async function resolveListPagesAsync(
+  module: ListPagesModuleData,
+  data: ListPagesExternalData,
+  template: CompiledTemplate,
+  parse: (source: string) => Promise<SyntaxTree>,
+): Promise<Element[]> {
+  if (data.pages.length === 0) return [];
+  const result: Element[] = [];
+
+  if (module["prepend-line"] && !module.separate) {
+    result.push(...(await parse(module["prepend-line"])).elements);
+  }
+  for (let i = 0; i < data.pages.length; i++) {
+    const page = data.pages[i];
+    if (!page) continue;
+    const variableContext: VariableContext = {
+      page,
+      index: i + 1,
+      total: data.totalCount,
+      limit: module.limit,
+      site: data.site,
+    };
+    const parsed = await parse(template(variableContext));
+    if (module.separate) {
+      result.push({
+        element: "container",
+        data: {
+          type: "div",
+          attributes: { class: "list-pages-item" },
+          elements: parsed.elements,
+        },
+      });
+    } else {
+      result.push(...parsed.elements);
+    }
+  }
+  if (module["append-line"] && !module.separate) {
+    result.push(...(await parse(module["append-line"])).elements);
+  }
+
+  return module.wrapper
+    ? [
+        {
+          element: "container",
+          data: {
+            type: "div",
+            attributes: { class: "list-pages-box" },
+            elements: result,
+          },
+        },
+      ]
+    : result;
+}
+
+async function resolveElementChildren(
+  element: Element,
+  context: ResolutionContext,
+  state: ResolutionState,
+): Promise<Element> {
+  if (element.element === "list") {
+    const items = [];
+    for (const item of element.data.items) {
+      if (item["item-type"] === "elements") {
+        items.push({ ...item, elements: await resolveElements(item.elements, context, state) });
+      } else {
+        const resolved = (await resolveElements([listElement(item.data)], context, state))[0];
+        items.push(resolved?.element === "list" ? { ...item, data: resolved.data } : item);
+      }
+    }
+    return { ...element, data: { ...element.data, items } };
+  }
+  if (element.element === "table") {
+    const rows = [];
+    for (const row of element.data.rows) {
+      const cells = [];
+      for (const cell of row.cells) {
+        cells.push({ ...cell, elements: await resolveElements(cell.elements, context, state) });
+      }
+      rows.push({ ...row, cells });
+    }
+    return { ...element, data: { ...element.data, rows } };
+  }
+  if (element.element === "definition-list") {
+    const entries = [];
+    for (const entry of element.data) {
+      entries.push({
+        ...entry,
+        key: await resolveElements(entry.key, context, state),
+        value: await resolveElements(entry.value, context, state),
+      });
+    }
+    return { ...element, data: entries };
+  }
+  if (element.element === "tab-view") {
+    const tabs = [];
+    for (const tab of element.data) {
+      tabs.push({ ...tab, elements: await resolveElements(tab.elements, context, state) });
+    }
+    return { ...element, data: tabs };
+  }
+  const children = getGenericElementChildren(element);
+  return children === null
+    ? element
+    : withGenericElementChildren(element, await resolveElements(children, context, state));
+}
+
+export function asParseResult(ast: SyntaxTree, diagnostics: Diagnostic[]): ParseResult {
+  return { ast, diagnostics };
+}