@astryxdesign/core 0.6.2 → 0.6.3-canary.0949cb1

package/src/Markdown/plugins/semanticFence.ts

@@ -0,0 +1,424 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file semanticFence.ts
+ * @input Declared fenced-code languages and typed extension-node factories
+ * @output Immutable Markdown transform that annotates eligible canonical code nodes
+ * @position Optional helper layer compiled onto the core transform protocol
+ */
+
+import type {
+  MarkdownAstBlockContent,
+  MarkdownAstCode,
+  MarkdownAstListItem,
+} from '../ast';
+import {
+  getMarkdownHelperOwnership,
+  markMarkdownTransformClaim,
+  markMarkdownTransformTrusted,
+  type MarkdownExtensionNode,
+  type MarkdownPluginData,
+  type MarkdownTransform,
+  type MarkdownTransformContext,
+} from './protocol';
+
+export interface MarkdownFenceContext<Language extends string> {
+  readonly code: string;
+  readonly language: Language;
+  readonly meta?: string;
+}
+
+export type MarkdownFenceNode<Node extends MarkdownExtensionNode> = Node & {
+  readonly type: 'extension';
+  readonly display: 'block';
+  readonly position?: never;
+  readonly source?: never;
+};
+
+export interface MarkdownFenceTransformOptions<
+  Languages extends readonly [string, ...string[]],
+  Node extends MarkdownExtensionNode<
+    string,
+    string,
+    MarkdownPluginData,
+    'block'
+  >,
+> {
+  /** Exact, case-sensitive fenced-code language identifiers this helper owns. */
+  readonly languages: Languages;
+  /**
+   * Creates typed semantic data for an eligible fence. Return null or undefined
+   * to retain Markdown's ordinary CodeBlock rendering.
+   */
+  readonly createNode: (
+    context: MarkdownFenceContext<Languages[number]>,
+  ) => MarkdownFenceNode<Node> | null | undefined;
+}
+
+interface MarkdownFenceProposal {
+  readonly node: MarkdownExtensionNode<
+    string,
+    string,
+    MarkdownPluginData,
+    'block'
+  >;
+}
+
+const markdownFenceProposal = Symbol('MarkdownFenceProposal');
+
+type FenceCode = MarkdownAstCode & {
+  readonly [markdownFenceProposal]?: MarkdownFenceProposal;
+};
+
+/** @internal Returns the first transform-owned proposal attached to a code node. */
+export function getMarkdownFenceProposal(
+  node: MarkdownAstCode,
+): MarkdownFenceProposal | undefined {
+  return (node as FenceCode)[markdownFenceProposal];
+}
+
+function cloneNestedPluginData(
+  value: unknown,
+  parent: object,
+  ancestors: ReadonlySet<object> | undefined,
+): MarkdownPluginData {
+  if (value == null || typeof value !== 'object') {
+    return clonePluginData(value, ancestors);
+  }
+  const nestedAncestors = new Set(ancestors);
+  nestedAncestors.add(parent);
+  return clonePluginData(value, nestedAncestors);
+}
+
+function clonePluginData(
+  value: unknown,
+  ancestors?: ReadonlySet<object>,
+): MarkdownPluginData {
+  if (
+    value == null ||
+    typeof value === 'boolean' ||
+    typeof value === 'string'
+  ) {
+    return value as MarkdownPluginData;
+  }
+  if (typeof value === 'number') {
+    if (!Number.isFinite(value)) {
+      throw new TypeError('invalid plugin data');
+    }
+    return value;
+  }
+  if (
+    typeof value !== 'object' ||
+    ancestors?.has(value) === true ||
+    (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype)
+  ) {
+    throw new TypeError('invalid plugin data');
+  }
+  let clone: MarkdownPluginData;
+  if (Array.isArray(value)) {
+    const items = new Array<MarkdownPluginData>(value.length);
+    for (let index = 0; index < value.length; index++) {
+      if (index in value) {
+        items[index] = cloneNestedPluginData(value[index], value, ancestors);
+      }
+    }
+    clone = Object.freeze(items);
+  } else {
+    const record: Record<string, MarkdownPluginData> = {};
+    for (const key in value) {
+      const nested = cloneNestedPluginData(
+        (value as Record<string, unknown>)[key],
+        value,
+        ancestors,
+      );
+      if (key === '__proto__') {
+        Object.defineProperty(record, key, {
+          configurable: true,
+          enumerable: true,
+          value: nested,
+          writable: true,
+        });
+      } else {
+        record[key] = nested;
+      }
+    }
+    clone = Object.freeze(record);
+  }
+  return clone;
+}
+
+function createProposal(
+  node: MarkdownFenceNode<
+    MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>
+  >,
+  pluginName: string,
+  hasRenderer: (nodeName: string) => boolean,
+): MarkdownFenceProposal {
+  if (
+    node == null ||
+    typeof node !== 'object' ||
+    node.type !== 'extension' ||
+    node.plugin !== pluginName ||
+    typeof node.name !== 'string' ||
+    node.name.trim() === '' ||
+    // Every extension node must have a renderer and a text projection
+    // (FR14). Checking it here is what lets Core run this helper on its
+    // trusted path: the node is fully validated before it is inserted.
+    !hasRenderer(node.name) ||
+    node.display !== 'block' ||
+    'source' in node ||
+    'position' in node
+  ) {
+    throw new TypeError(
+      'Markdown fence createNode must return an owned block extension node with finite data and a registered renderer',
+    );
+  }
+
+  let data: MarkdownPluginData;
+  try {
+    data = clonePluginData(node.data);
+  } catch {
+    throw new TypeError(
+      'Markdown fence createNode must return an owned block extension node with finite data and a registered renderer',
+    );
+  }
+  return Object.freeze({
+    node: Object.freeze({
+      type: 'extension' as const,
+      plugin: node.plugin,
+      name: node.name,
+      display: 'block' as const,
+      data,
+    }),
+  });
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    'then' in value &&
+    typeof value.then === 'function'
+  );
+}
+
+function consumeInvalidAsyncNode(
+  value: PromiseLike<unknown>,
+  report: (message: string) => void,
+): void {
+  void Promise.resolve(value).then(
+    () => report('Markdown fence createNode returned a Promise'),
+    () => report('Markdown fence createNode Promise rejected'),
+  );
+}
+
+function annotateCode(
+  node: MarkdownAstCode,
+  languages: ReadonlySet<string>,
+  pluginName: string,
+  hasRenderer: (nodeName: string) => boolean,
+  createNode: (
+    context: MarkdownFenceContext<string>,
+  ) =>
+    | MarkdownFenceNode<
+        MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>
+      >
+    | null
+    | undefined,
+  report: (message: string) => void,
+): MarkdownAstCode {
+  if (
+    node.lang == null ||
+    !languages.has(node.lang) ||
+    getMarkdownFenceProposal(node) != null
+  ) {
+    return node;
+  }
+
+  const proposalNode = createNode(
+    Object.freeze({
+      code: node.value,
+      language: node.lang,
+      ...(node.meta == null ? {} : {meta: node.meta}),
+    }),
+  );
+  if (isPromiseLike(proposalNode)) {
+    consumeInvalidAsyncNode(proposalNode, report);
+    throw new TypeError('Markdown fence createNode must be synchronous');
+  }
+  if (proposalNode == null) {
+    return node;
+  }
+
+  const annotated = {...node};
+  Object.defineProperty(annotated, markdownFenceProposal, {
+    configurable: false,
+    enumerable: true,
+    value: createProposal(proposalNode, pluginName, hasRenderer),
+    writable: false,
+  });
+  return annotated;
+}
+
+function transformBlocks(
+  blocks: ReadonlyArray<MarkdownAstBlockContent<MarkdownExtensionNode>>,
+  languages: ReadonlySet<string>,
+  pluginName: string,
+  hasRenderer: (nodeName: string) => boolean,
+  createNode: (
+    context: MarkdownFenceContext<string>,
+  ) =>
+    | MarkdownFenceNode<
+        MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>
+      >
+    | null
+    | undefined,
+  report: (message: string) => void,
+): ReadonlyArray<MarkdownAstBlockContent<MarkdownExtensionNode>> {
+  let next: MarkdownAstBlockContent<MarkdownExtensionNode>[] | undefined;
+  for (let index = 0; index < blocks.length; index++) {
+    const block = blocks[index];
+    let replacement: MarkdownAstBlockContent<MarkdownExtensionNode>;
+    switch (block.type) {
+      case 'code':
+        replacement = annotateCode(
+          block,
+          languages,
+          pluginName,
+          hasRenderer,
+          createNode,
+          report,
+        );
+        break;
+      case 'blockquote': {
+        const children = transformBlocks(
+          block.children,
+          languages,
+          pluginName,
+          hasRenderer,
+          createNode,
+          report,
+        );
+        replacement =
+          children === block.children ? block : {...block, children};
+        break;
+      }
+      case 'list': {
+        let items: MarkdownAstListItem<MarkdownExtensionNode>[] | undefined;
+        for (
+          let itemIndex = 0;
+          itemIndex < block.children.length;
+          itemIndex++
+        ) {
+          const item = block.children[itemIndex];
+          const itemChildren = transformBlocks(
+            item.children,
+            languages,
+            pluginName,
+            hasRenderer,
+            createNode,
+            report,
+          );
+          if (itemChildren === item.children) {
+            items?.push(item);
+            continue;
+          }
+          items ??= block.children.slice(0, itemIndex);
+          items.push({...item, children: itemChildren});
+        }
+        replacement = items == null ? block : {...block, children: items};
+        break;
+      }
+      case 'heading':
+      case 'paragraph':
+      case 'math':
+      case 'table':
+      case 'thematicBreak':
+      case 'image':
+      case 'extension':
+        replacement = block;
+        break;
+    }
+    if (next === undefined && replacement !== block) {
+      next = blocks.slice(0, index);
+    }
+    next?.push(replacement);
+  }
+  return next ?? blocks;
+}
+
+export function createMarkdownFenceTransform<
+  const Languages extends readonly [string, ...string[]],
+  const Node extends MarkdownExtensionNode<
+    string,
+    string,
+    MarkdownPluginData,
+    'block'
+  >,
+>(
+  options: MarkdownFenceTransformOptions<Languages, Node>,
+): MarkdownTransform<Node> {
+  if (
+    !Array.isArray(options.languages) ||
+    options.languages.length === 0 ||
+    options.languages.some(
+      language => typeof language !== 'string' || language.trim() === '',
+    )
+  ) {
+    throw new TypeError('Markdown fence languages must be non-empty strings');
+  }
+  if (new Set(options.languages).size !== options.languages.length) {
+    throw new TypeError('Markdown fence languages must be unique');
+  }
+  if (typeof options.createNode !== 'function') {
+    throw new TypeError('Markdown fence createNode must be a function');
+  }
+
+  const declaredLanguages = Object.freeze([...options.languages]);
+  const languages = new Set<string>(declaredLanguages);
+  const sourceNeedles = Object.freeze(
+    declaredLanguages.flatMap(language => [
+      `\`\`\`${language}`,
+      `~~~${language}`,
+    ]),
+  );
+  const createNode = options.createNode as (
+    context: MarkdownFenceContext<string>,
+  ) =>
+    | MarkdownFenceNode<
+        MarkdownExtensionNode<string, string, MarkdownPluginData, 'block'>
+      >
+    | null
+    | undefined;
+  const transform: MarkdownTransform<Node> = (
+    root,
+    context: MarkdownTransformContext,
+  ) => {
+    const ownership = getMarkdownHelperOwnership(context);
+    if (ownership == null) {
+      throw new TypeError(
+        'Markdown fence transforms must run through createMarkdownPlugin',
+      );
+    }
+    const children = transformBlocks(
+      root.children,
+      languages,
+      ownership.pluginName,
+      ownership.hasRenderer,
+      createNode,
+      context.report,
+    );
+    return children === root.children ? root : {...root, children};
+  };
+
+  // Every node this helper inserts is validated above against the same
+  // rules Core applies to plugin-authored output — owned plugin name,
+  // registered renderer, representable frozen data, no authored provenance
+  // — and nothing else in the tree is touched. Core may therefore skip
+  // revalidating the whole document after it runs.
+  return markMarkdownTransformTrusted(
+    markMarkdownTransformClaim(transform, source =>
+      sourceNeedles.some(needle => source.includes(needle)),
+    ) as MarkdownTransform<never>,
+  );
+}