@astryxdesign/core 0.6.1 → 0.6.2-canary.023c3e4

package/src/Markdown/parser/index.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input Markdown source and public parser options
+ * @output Server-safe legacy and canonical Markdown parser entry points and types
+ * @position Public subpath entry point: `@astryxdesign/core/Markdown/parser`
+ */
+
+export {
+  createIncrementalState,
+  parseInline,
+  parseInlineAst,
+  parseMarkdown,
+  parseMarkdownAst,
+  parseMarkdownIncremental,
+} from '../parser';
+export type {
+  BlockNode,
+  BlockNodeWithMath,
+  MathBlockNode,
+  InlineNode,
+  InlineNodeWithMath,
+  MathInlineNode,
+  SourceRange,
+  ListItemNode,
+  TableCellNode,
+  TableAlignment,
+  ParseOptions,
+  MathParseOptions,
+  IncrementalParseOptions,
+  IncrementalMathParseOptions,
+  IncrementalState as IncrementalParseState,
+} from '../parser';
+export type {
+  MarkdownAstPoint,
+  MarkdownAstDataValue,
+  MarkdownAstPosition,
+  MarkdownAstNodeBase,
+  MarkdownAstExtensionNode,
+  MarkdownAstText,
+  MarkdownAstInlineCode,
+  MarkdownAstInlineMath,
+  MarkdownAstLink,
+  MarkdownAstImage,
+  MarkdownAstCitation,
+  MarkdownAstBreak,
+  MarkdownAstPhrasingContent,
+  MarkdownAstHeading,
+  MarkdownAstParagraph,
+  MarkdownAstCode,
+  MarkdownAstMath,
+  MarkdownAstBlockquote,
+  MarkdownAstList,
+  MarkdownAstListItem,
+  MarkdownAstTable,
+  MarkdownAstTableRow,
+  MarkdownAstTableCell,
+  MarkdownAstThematicBreak,
+  MarkdownAstBlockContent,
+  MarkdownAstRoot,
+  MarkdownAstNodeMap,
+  MarkdownAstNode,
+} from '../ast';

package/src/Markdown/parser.perf.test.ts

@@ -9,6 +9,8 @@ import {
 } from './parser';
 import type {BlockNode, ParseOptions} from './parser';
 
+type PerfParseOptions = ParseOptions;
+
 function generateAIResponse(paragraphs: number): string {
   const sections: string[] = [];
   for (let i = 0; i < paragraphs; i++) {
@@ -81,7 +83,7 @@ function simulateStreamingIncremental(
 function blocksBuiltPerChunk(
   fullText: string,
   chunkSize: number,
-  options?: ParseOptions,
+  options?: PerfParseOptions,
 ): number[] {
   const state = createIncrementalState();
   let previous: ReadonlySet<BlockNode> = new Set();

package/src/Markdown/parser.public.test.ts

@@ -0,0 +1,103 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file parser.public.test.ts
+ * @input Imports the documented Markdown parser-only package subpath
+ * @output Runtime and type evidence for its canonical server-safe contract
+ * @position Public package-contract test for @astryxdesign/core/Markdown/parser
+ */
+
+import {readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import {describe, expect, expectTypeOf, it} from 'vitest';
+import {
+  createMarkdownFrontmatter,
+  createMarkdownPlugin,
+} from '@astryxdesign/core/Markdown/plugins';
+import {
+  createIncrementalState,
+  parseInline,
+  parseInlineAst,
+  parseMarkdown,
+  parseMarkdownAst,
+  parseMarkdownIncremental,
+} from '@astryxdesign/core/Markdown/parser';
+import type {
+  BlockNode,
+  InlineNode,
+  MarkdownAstPhrasingContent,
+  MarkdownAstRoot,
+} from '@astryxdesign/core/Markdown/parser';
+
+describe('@astryxdesign/core/Markdown/parser', () => {
+  it('is a generated public package subpath', () => {
+    const packageJson = JSON.parse(
+      readFileSync(join(process.cwd(), 'packages/core/package.json'), 'utf8'),
+    ) as {
+      exports: Record<string, unknown>;
+    };
+    const entrySources = [
+      'packages/core/src/Markdown/parser/index.ts',
+      'packages/core/src/Markdown/parser.ts',
+      'packages/core/src/Markdown/plugins/index.ts',
+      'packages/core/src/Markdown/plugins/protocol.ts',
+      'packages/core/src/Markdown/plugins/frontmatter.ts',
+    ].map(path => readFileSync(join(process.cwd(), path), 'utf8'));
+
+    expect(packageJson.exports['./Markdown/parser']).toEqual({
+      source: './src/Markdown/parser/index.ts',
+      types: './dist/Markdown/parser/index.d.ts',
+      default: './dist/Markdown/parser/index.js',
+    });
+    for (const entrySource of entrySources) {
+      expect(entrySource).not.toMatch(/^\s*['"]use client['"]/m);
+    }
+  });
+
+  it('exposes legacy and canonical parser results from a server-only entry point', () => {
+    const source = '# Heading\n\nParagraph';
+    const blockAst = parseMarkdownAst(source);
+    const inlineAst = parseInlineAst('**bold**');
+
+    expect(blockAst).toMatchObject({
+      type: 'root',
+      children: [{type: 'heading', depth: 1}, {type: 'paragraph'}],
+    });
+    expect(inlineAst).toMatchObject([{type: 'strong'}]);
+    expect(parseMarkdown(source)[0]).toMatchObject({type: 'heading', level: 1});
+    expect(parseInline('**bold**')[0]).toMatchObject({type: 'bold'});
+    expect(parseMarkdownIncremental(source, createIncrementalState())).toEqual(
+      parseMarkdown(source),
+    );
+
+    const canonicalBlockAst: MarkdownAstRoot = blockAst;
+    const canonicalInlineAst: ReadonlyArray<MarkdownAstPhrasingContent> =
+      inlineAst;
+    expect(canonicalBlockAst).toBe(blockAst);
+    expect(canonicalInlineAst).toBe(inlineAst);
+    expectTypeOf(parseMarkdown(source)).toEqualTypeOf<BlockNode[]>();
+    expectTypeOf(parseInline('text')).toEqualTypeOf<InlineNode[]>();
+  });
+
+  it('runs typed plugins through the server-safe parser boundary', () => {
+    const frontmatter = createMarkdownFrontmatter({
+      name: 'server-document-metadata',
+      parse: fields => ({title: fields.title ?? 'Untitled'}),
+    });
+    let title: string | undefined;
+    const observer = createMarkdownPlugin({
+      name: 'server-metadata-observer',
+      apiVersion: 1,
+      transform(root) {
+        title = frontmatter.getMetadata(root)?.title;
+        return root;
+      },
+    });
+    const root = parseMarkdownAst('---\ntitle: Server proof\n---\n# Body', {
+      plugins: [frontmatter.plugin, observer],
+    });
+
+    expect(title).toBe('Server proof');
+    expect(root.children).toMatchObject([{type: 'heading', depth: 1}]);
+  });
+});

package/src/Markdown/parser.test.ts

@@ -42,6 +42,73 @@ describe('parseInline', () => {
     expect(result).toEqual([{type: 'code', content: 'const x'}]);
   });
 
+  it('leaves math delimiters as literal text by default', () => {
+    expect(parseInline('Euler: $e^{i * pi} + 1 = 0$.')).toEqual([
+      {type: 'text', content: 'Euler: $e^{i * pi} + 1 = 0$.'},
+    ]);
+  });
+
+  it('parses inline math before Markdown formatting when explicitly enabled', () => {
+    expect(parseInline('Euler: $e^{i * pi} + 1 = 0$.', {math: true})).toEqual([
+      {type: 'text', content: 'Euler: '},
+      {type: 'math', value: 'e^{i * pi} + 1 = 0'},
+      {type: 'text', content: '.'},
+    ]);
+  });
+
+  it('preserves escaped delimiters inside math and leaves escaped openers literal', () => {
+    expect(
+      parseInline('Price: \\$5; formula: $x \\$ y$.', {math: true}),
+    ).toEqual([
+      {type: 'text', content: 'Price: '},
+      {type: 'text', content: '$5; formula: '},
+      {type: 'math', value: 'x \\$ y'},
+      {type: 'text', content: '.'},
+    ]);
+  });
+
+  it('leaves an unmatched inline math delimiter literal', () => {
+    expect(parseInline('The value is $x + 1.', {math: true})).toEqual([
+      {type: 'text', content: 'The value is $x + 1.'},
+    ]);
+  });
+
+  it('does not mistake paired currency amounts for inline math', () => {
+    expect(
+      parseInline('Tickets cost $20 and $30 today.', {math: true}),
+    ).toEqual([{type: 'text', content: 'Tickets cost $20 and $30 today.'}]);
+    expect(parseInline('$x$5 and $y$', {math: true})).toEqual([
+      {type: 'text', content: '$x$5 and '},
+      {type: 'math', value: 'y'},
+    ]);
+  });
+
+  it('allows an inline expression to begin with a number', () => {
+    expect(parseInline('Result: $2 + 2$.', {math: true})).toEqual([
+      {type: 'text', content: 'Result: '},
+      {type: 'math', value: '2 + 2'},
+      {type: 'text', content: '.'},
+    ]);
+  });
+
+  it('does not treat non-block double-dollar runs as inline math', () => {
+    expect(parseInline('Keep $$x + y$$ literal.', {math: true})).toEqual([
+      {type: 'text', content: 'Keep $$x + y$$ literal.'},
+    ]);
+  });
+
+  it('keeps code and link destinations opaque while parsing math in link labels', () => {
+    expect(parseInline('`$code$` [$label$](/price/$5)', {math: true})).toEqual([
+      {type: 'code', content: '$code$'},
+      {type: 'text', content: ' '},
+      {
+        type: 'link',
+        href: '/price/$5',
+        children: [{type: 'math', value: 'label'}],
+      },
+    ]);
+  });
+
   it('parses links', () => {
     const result = parseInline('[click](https://example.com)');
     expect(result[0].type).toBe('link');
@@ -270,6 +337,61 @@ describe('parseMarkdown', () => {
     }
   });
 
+  it('parses display math only when explicitly enabled', () => {
+    const source = '$$\n\\int_0^1 x^2 \\, dx\n$$';
+    expect(parseMarkdown(source)).not.toContainEqual({
+      type: 'math',
+      value: '\\int_0^1 x^2 \\, dx',
+    });
+    expect(parseMarkdown(source, {math: true})).toEqual([
+      {type: 'math', value: '\\int_0^1 x^2 \\, dx'},
+    ]);
+  });
+
+  it('parses a same-line display math block', () => {
+    expect(parseMarkdown('$$E = mc^2$$', {math: true})).toEqual([
+      {type: 'math', value: 'E = mc^2'},
+    ]);
+  });
+
+  it('keeps empty display delimiters literal', () => {
+    const source = '$$\n$$';
+    expect(parseMarkdown(source, {math: true})).toEqual(parseMarkdown(source));
+  });
+
+  it('leaves unmatched display math delimiters literal', () => {
+    const source = '$$\nx + y';
+    expect(parseMarkdown(source, {math: true})).toEqual(parseMarkdown(source));
+  });
+
+  it('leaves escaped display delimiters literal', () => {
+    const blocks = parseMarkdown('\\$\\$\nx + y\n\\$\\$', {math: true});
+    expect(blocks.some(block => block.type === 'math')).toBe(false);
+  });
+
+  it('reports a display-math source range including its delimiters', () => {
+    const source = 'Before.\n\n$$\nx + y\n$$\n\nAfter.';
+    const blocks = parseMarkdown(source, {math: true, sourceRanges: true});
+    expect(blocks[1]?.range).toEqual({start: 9, end: 20});
+    expect(source.slice(blocks[1].range?.start, blocks[1].range?.end)).toBe(
+      '$$\nx + y\n$$',
+    );
+  });
+
+  it('keeps fenced code opaque when math parsing is enabled', () => {
+    expect(parseMarkdown('```tex\n$x$\n$$y$$\n```', {math: true})).toEqual([
+      {type: 'codeblock', language: 'tex', content: '$x$\n$$y$$'},
+    ]);
+  });
+
+  it('does not collect link definitions from display math', () => {
+    const blocks = parseMarkdown('$$\n[x]: /not-a-link\n$$\n\n[x]', {
+      math: true,
+    });
+    expect(blocks[0]).toEqual({type: 'math', value: '[x]: /not-a-link'});
+    expect(JSON.stringify(blocks[1])).not.toContain('"type":"link"');
+  });
+
   it('parses blockquotes', () => {
     const result = parseMarkdown('> This is a quote');
     expect(result[0].type).toBe('blockquote');