Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
14.3 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file textTransform.test.ts
 * @input Text-transform helper selectors, callbacks, and protected contexts
 * @output Behavioral, ordering, typing, and work-count regression coverage
 * @position Acceptance tests for the optional Markdown text helper
 */

import {describe, expect, expectTypeOf, it, vi} from 'vitest';
import {parseInline, parseMarkdown, parseMarkdownAst} from '../parser';
import {createMarkdownPlugin} from './protocol';
import type {MarkdownExtensionNode} from './protocol';
import {createMarkdownTextTransform} from './textTransform';
import type {MarkdownTextTransformContext} from './textTransform';

type TodoNode = MarkdownExtensionNode<
  'todo-labels',
  'todo',
  {readonly label: string},
  'inline'
>;

function todoPlugin(
  onReplace?: (context: MarkdownTextTransformContext) => void,
) {
  return createMarkdownPlugin<'todo-labels', TodoNode>({
    name: 'todo-labels',
    apiVersion: 1,
    transform: createMarkdownTextTransform<TodoNode>({
      pattern: /TODO/g,
      requiredSubstrings: ['TODO'],
      replace(_match, context) {
        onReplace?.(context);
        return {
          type: 'extension',
          plugin: 'todo-labels',
          name: 'todo',
          display: 'inline',
          data: {label: 'TODO'},
        };
      },
    }),
    renderers: {
      todo: {
        render: ({node}) => node.data.label,
        toText: node => node.data.label,
      },
    },
  });
}

function extensionCount(value: unknown): number {
  if (Array.isArray(value)) {
    return value.reduce<number>(
      (count, child) => count + extensionCount(child),
      0,
    );
  }
  if (value == null || typeof value !== 'object') {
    return 0;
  }
  const record = value as Record<string, unknown>;
  const own = record.type === 'extension' ? 1 : 0;
  return (
    own +
    Object.values(record).reduce<number>(
      (count, child) => count + extensionCount(child),
      0,
    )
  );
}

describe('createMarkdownTextTransform', () => {
  it('replaces eligible prose and preserves protected contexts', () => {
    const parents: string[] = [];
    const plugin = todoPlugin(context => parents.push(context.parentType));
    const blocks = parseMarkdown(
      [
        'TODO **TODO** [TODO](/tasks) `TODO` [source]',
        '',
        '> TODO',
        '',
        '| Item |',
        '| --- |',
        '| TODO |',
        '',
        '```text',
        'TODO',
        '```',
      ].join('\n'),
      {plugins: [plugin], sourceIds: new Set(['source'])},
    );

    expect(extensionCount(blocks)).toBe(4);
    expect(parents).toEqual(['paragraph', 'strong', 'paragraph', 'tableCell']);
    expect(JSON.stringify(blocks)).toContain('"type":"link","href":"/tasks"');
    expect(JSON.stringify(blocks)).toContain('"type":"code","content":"TODO"');
  });

  it('runs helpers in plugin order and supports removal', () => {
    const replace = (name: string, pattern: RegExp, value: string) =>
      createMarkdownPlugin({
        name,
        apiVersion: 1,
        transform: createMarkdownTextTransform({
          pattern,
          requiredSubstrings: [pattern.source],
          replace: () => (value === '' ? [] : {type: 'text' as const, value}),
        }),
      });

    expect(
      parseMarkdown('A', {
        plugins: [replace('a-to-b', /A/g, 'B'), replace('b-to-c', /B/g, 'C')],
      }),
    ).toMatchObject([
      {
        type: 'paragraph',
        children: [{type: 'text', content: 'C'}],
      },
    ]);
    expect(
      parseMarkdown('Remove me', {
        plugins: [replace('remove', /Remove /g, '')],
      }),
    ).toMatchObject([
      {type: 'paragraph', children: [{type: 'text', content: 'me'}]},
    ]);
  });

  it('clones a hoisted replacement for each claim', () => {
    const replacement = {type: 'text' as const, value: 'done'};
    const plugin = createMarkdownPlugin({
      name: 'hoisted-replacement',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /X/g,
        requiredSubstrings: ['X'],
        replace: () => replacement,
      }),
    });

    expect(parseMarkdown('X X', {plugins: [plugin]})).toMatchObject([
      {
        type: 'paragraph',
        children: [
          {type: 'text', content: 'done'},
          {type: 'text', content: ' '},
          {type: 'text', content: 'done'},
        ],
      },
    ]);
  });

  it('does not invoke callbacks for absent or protected-only matches', () => {
    let replacements = 0;
    const plugin = todoPlugin(() => replacements++);

    parseMarkdown('No work here.', {plugins: [plugin]});
    expect(replacements).toBe(0);
    parseMarkdown('`TODO`\n\n```text\nTODO\n```', {plugins: [plugin]});
    expect(replacements).toBe(0);
  });

  it('uses case-insensitive source claims with case-insensitive patterns', () => {
    const plugin = createMarkdownPlugin({
      name: 'case-insensitive',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /todo/gi,
        requiredSubstrings: ['todo'],
        replace: () => ({type: 'text', value: 'done'}),
      }),
    });

    expect(parseMarkdown('TODO', {plugins: [plugin]})).toMatchObject([
      {type: 'paragraph', children: [{type: 'text', content: 'done'}]},
    ]);
    const unicodeCaseFold = createMarkdownPlugin({
      name: 'unicode-case-fold',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /Ξ£/gi,
        requiredSubstrings: ['Ξ£'],
        replace: () => ({type: 'text', value: 'sigma'}),
      }),
    });
    expect(parseMarkdown('Ο‚', {plugins: [unicodeCaseFold]})).toMatchObject([
      {type: 'paragraph', children: [{type: 'text', content: 'sigma'}]},
    ]);
    const digits = createMarkdownPlugin({
      name: 'digits-without-prefilter',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /\d+/g,
        replace: match => ({type: 'text', value: `[${match[0]}]`}),
      }),
    });
    expect(parseMarkdown('Item 42', {plugins: [digits]})).toMatchObject([
      {
        type: 'paragraph',
        children: [
          {type: 'text', content: 'Item '},
          {type: 'text', content: '[42]'},
        ],
      },
    ]);
  });

  it('supports bounded claim extension and decline', () => {
    let replacements = 0;
    const plugin = createMarkdownPlugin({
      name: 'hash-tags',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /#/g,
        requiredSubstrings: ['#'],
        getEndIndex(text, match) {
          const end = text.indexOf(' ', match.index);
          return end < 0 ? text.length : end;
        },
        replace(match) {
          replacements++;
          return {type: 'text', value: match.index === 0 ? 'tag' : 'nested'};
        },
      }),
    });

    expect(parseInline('#one #two', {plugins: [plugin]})).toMatchObject([
      {type: 'text', content: 'tag'},
      {type: 'text', content: ' '},
      {type: 'text', content: 'nested'},
    ]);
    expect(replacements).toBe(2);
  });

  it('supports accepted zero-width insertions at text boundaries', () => {
    const start = createMarkdownPlugin({
      name: 'insert-start',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /^/g,
        replace: () => ({type: 'text', value: '['}),
      }),
    });
    const end = createMarkdownPlugin({
      name: 'insert-end',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /$/g,
        replace: () => ({type: 'text', value: ']'}),
      }),
    });

    expect(parseMarkdown('value', {plugins: [start]})).toMatchObject([
      {
        type: 'paragraph',
        children: [
          {type: 'text', content: '['},
          {type: 'text', content: 'value'},
        ],
      },
    ]);
    expect(parseMarkdown('value', {plugins: [end]})).toMatchObject([
      {
        type: 'paragraph',
        children: [
          {type: 'text', content: 'value'},
          {type: 'text', content: ']'},
        ],
      },
    ]);
  });

  it('advances declined zero-width matches by Unicode code point', () => {
    let replacements = 0;
    const astral = createMarkdownPlugin({
      name: 'astral-zero-width',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /(?=πŸ˜€)/gu,
        requiredSubstrings: ['πŸ˜€'],
        getEndIndex: () => false,
        replace: () => {
          replacements++;
          return {type: 'text', value: 'unexpected'};
        },
      }),
    });
    const end = createMarkdownPlugin({
      name: 'end-zero-width',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /$/gu,
        requiredSubstrings: ['πŸ˜€'],
        getEndIndex: () => false,
        replace: () => {
          replacements++;
          return {type: 'text', value: 'unexpected'};
        },
      }),
    });

    expect(parseMarkdown('πŸ˜€', {plugins: [astral, end]})).toMatchObject([
      {type: 'paragraph', children: [{type: 'text', content: 'πŸ˜€'}]},
    ]);
    expect(replacements).toBe(0);
  });

  it('requires a global pattern and keeps the helper typed as a transform', () => {
    expect(() =>
      createMarkdownTextTransform({
        pattern: /TODO/,
        requiredSubstrings: ['TODO'],
        replace: () => ({type: 'text', value: 'done'}),
      }),
    ).toThrow(/global flag/);
    expect(() =>
      createMarkdownTextTransform({
        pattern: /TODO/g,
        requiredSubstrings: [] as never,
        replace: () => ({type: 'text', value: 'done'}),
      }),
    ).toThrow(/requiredSubstring/);
    expect(() =>
      createMarkdownTextTransform({
        pattern: /TODO/g,
        requiredSubstrings: [42] as never,
        replace: () => ({type: 'text', value: 'done'}),
      }),
    ).toThrow(/requiredSubstrings/);
    const ownedTransform = createMarkdownTextTransform<TodoNode>({
      pattern: /TODO/g,
      requiredSubstrings: ['TODO'],
      replace: () => ({
        type: 'extension',
        plugin: 'todo-labels',
        name: 'todo',
        display: 'inline',
        data: {label: 'TODO'},
      }),
    });
    function compileOnlyRendererRequirement() {
      // @ts-expect-error a helper that owns extension nodes requires renderers
      createMarkdownPlugin({
        name: 'todo-labels',
        apiVersion: 1,
        transform: ownedTransform,
      });
    }
    expectTypeOf(compileOnlyRendererRequirement).toBeFunction();
    expectTypeOf(createMarkdownTextTransform).toBeFunction();
  });

  it('adopts a fresh replacement node and freezes it against later writes', () => {
    // A callback that builds a node per match hands over a fresh object, so
    // the helper puts it straight into the tree rather than copying it. That
    // is only safe because the node is frozen on the way in: whoever still
    // holds the reference cannot reach into the document afterwards.
    const handedOver: {type: 'text'; value: string}[] = [];
    const plugin = createMarkdownPlugin({
      name: 'fresh-nodes',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /TODO/g,
        requiredSubstrings: ['TODO'],
        replace: () => {
          const node = {type: 'text' as const, value: 'done'};
          handedOver.push(node);
          return node;
        },
      }),
    });

    const blocks = parseMarkdown('TODO and TODO again', {plugins: [plugin]});
    expect(handedOver).toHaveLength(2);
    expect(handedOver.every(node => Object.isFrozen(node))).toBe(true);

    // A late write by the caller is rejected and the document is unaffected.
    expect(() => {
      'use strict';
      handedOver[0].value = 'HACKED';
    }).toThrow(TypeError);
    expect(blocks).toEqual([
      {
        type: 'paragraph',
        children: [
          {type: 'text', content: 'done'},
          {type: 'text', content: ' and '},
          {type: 'text', content: 'done'},
          {type: 'text', content: ' again'},
        ],
      },
    ]);
  });

  it('copies a replacement node the callback hands over more than once', () => {
    // One object cannot occupy two positions in the tree, and the first
    // position's node is already frozen. A callback that returns the same
    // object for every match therefore gets a copy from the second match on.
    const shared = {type: 'text' as const, value: 'done'};
    const plugin = createMarkdownPlugin({
      name: 'shared-node',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /TODO/g,
        requiredSubstrings: ['TODO'],
        replace: () => shared,
      }),
    });

    const root = parseMarkdownAst('TODO and TODO again', {plugins: [plugin]});
    const paragraph = root.children[0];
    if (paragraph.type !== 'paragraph') {
      throw new Error('Expected a paragraph');
    }
    const [first, , third] = paragraph.children;
    expect(first).not.toBe(third);
    expect(first).toEqual({type: 'text', value: 'done'});
    expect(third).toEqual({type: 'text', value: 'done'});

    // Both documents agree with a run whose callback allocates per match.
    expect(parseMarkdown('TODO and TODO again', {plugins: [plugin]})).toEqual(
      parseMarkdown('TODO and TODO again', {
        plugins: [
          createMarkdownPlugin({
            name: 'per-match-node',
            apiVersion: 1,
            transform: createMarkdownTextTransform({
              pattern: /TODO/g,
              requiredSubstrings: ['TODO'],
              replace: () => ({type: 'text', value: 'done'}),
            }),
          }),
        ],
      }),
    );
  });

  it('still rejects an unrepresentable node without freezing the batch', () => {
    const rejected = {
      type: 'text' as const,
      value: 'ok',
      position: {start: {offset: 0}, end: {offset: 2}},
    };
    const warning = vi.spyOn(console, 'warn').mockImplementation(() => {});
    const plugin = createMarkdownPlugin({
      name: 'forged-provenance',
      apiVersion: 1,
      transform: createMarkdownTextTransform({
        pattern: /TODO/g,
        requiredSubstrings: ['TODO'],
        replace: () => rejected as never,
      }),
    });

    // Authored provenance is refused, the document keeps its source text,
    // and the caller's object is left exactly as it was.
    expect(parseMarkdown('TODO', {plugins: [plugin]})).toEqual(
      parseMarkdown('TODO'),
    );
    expect(Object.isFrozen(rejected)).toBe(false);
    expect(warning).toHaveBeenCalled();
    warning.mockRestore();
  });
});