@hutusi/amytis 1.15.0 → 1.16.0

package/src/lib/rst.test.ts

@@ -41,17 +41,227 @@ describe('rst utils', () => {
     expect(markdown).toContain('![Test image](./images/test.svg)');
   });
 
-  test('does not treat generic directives as literal code blocks', () => {
+  test('propagates :linenos:, :emphasize-lines:, and :caption: into the fence info string', () => {
+    const markdown = rstToMarkdown([
+      '.. code-block:: python',
+      '   :linenos:',
+      '   :emphasize-lines: 1,3-5',
+      '   :caption: app.py',
+      '',
+      '  def fib(n):',
+      '      if n < 2:',
+      '          return n',
+      '      return fib(n - 1) + fib(n - 2)',
+    ].join('\n'));
+
+    expect(markdown).toContain('```python title="app.py" linenos {1,3-5}');
+    expect(markdown).toContain('def fib(n):');
+  });
+
+  test(':language: option overrides the directive language', () => {
+    const markdown = rstToMarkdown([
+      '.. code-block::',
+      '   :language: rust',
+      '',
+      '  fn main() {}',
+    ].join('\n'));
+
+    expect(markdown).toContain('```rust');
+    expect(markdown).toContain('fn main() {}');
+  });
+
+  test('converts figure directives the same way as image directives', () => {
+    const bare = rstToMarkdown('.. figure:: _static/redis.svg');
+    expect(bare).toContain('![](_static/redis.svg)');
+
+    const withAlt = rstToMarkdown([
+      '.. figure:: ./images/diagram.svg',
+      '   :alt: A diagram',
+    ].join('\n'));
+    expect(withAlt).toContain('![A diagram](./images/diagram.svg)');
+  });
+
+  test('renders .. note:: as a markdown blockquote with a bold label', () => {
     const markdown = rstToMarkdown([
       '.. note::',
       '',
       '   Keep this as prose.',
     ].join('\n'));
 
-    expect(markdown).toContain('.. note::');
+    expect(markdown).toContain('> **Note**');
+    expect(markdown).toContain('> Keep this as prose.');
+    expect(markdown).not.toContain('.. note::');
     expect(markdown).not.toContain('```');
   });
 
+  test('renders all admonition kinds and preserves inline rST + blank lines', () => {
+    const warning = rstToMarkdown([
+      '.. WARNING::',
+      '',
+      '   First line with ``code``.',
+      '',
+      '   Second paragraph.',
+    ].join('\n'));
+
+    expect(warning).toContain('> **Warning**');
+    expect(warning).toContain('> First line with `code`.');
+    expect(warning).toContain('> Second paragraph.');
+    expect(warning.split('\n').filter((line) => line === '>').length).toBeGreaterThanOrEqual(2);
+
+    for (const kind of ['tip', 'caution', 'attention', 'important', 'hint', 'danger', 'error']) {
+      const md = rstToMarkdown(`.. ${kind}::\n\n   body`);
+      const label = kind.charAt(0).toUpperCase() + kind.slice(1);
+      expect(md).toContain(`> **${label}**`);
+      expect(md).toContain('> body');
+    }
+  });
+
+  test('passes unknown directives through as plain text', () => {
+    const markdown = rstToMarkdown([
+      '.. unknownthing::',
+      '',
+      '   should not be swallowed',
+    ].join('\n'));
+
+    expect(markdown).toContain('.. unknownthing::');
+    expect(markdown).not.toContain('> **Unknownthing**');
+  });
+
+  test('handles single-line admonitions and inline body with indented continuation', () => {
+    const singleLine = rstToMarkdown('.. note:: Quick reminder.');
+    expect(singleLine).toContain('> **Note**');
+    expect(singleLine).toContain('> Quick reminder.');
+    expect(singleLine).not.toContain('.. note::');
+
+    const withContinuation = rstToMarkdown([
+      '.. note:: 特别要说明的是，本文的内容不涉及任何真实的设计',
+      '   示例，和任何真正的商用秘密无关。',
+    ].join('\n'));
+    expect(withContinuation).toContain('> **Note**');
+    expect(withContinuation).toContain('> 特别要说明的是，本文的内容不涉及任何真实的设计');
+    expect(withContinuation).toContain('> 示例，和任何真正的商用秘密无关。');
+    expect(withContinuation).not.toContain('.. note::');
+
+    const withParagraphBreak = rstToMarkdown([
+      '.. note:: First paragraph.',
+      '',
+      '   Second paragraph.',
+    ].join('\n'));
+    const lines = withParagraphBreak.split('\n');
+    const firstIdx = lines.findIndex((l) => l === '> First paragraph.');
+    const secondIdx = lines.findIndex((l) => l === '> Second paragraph.');
+    expect(firstIdx).toBeGreaterThan(-1);
+    expect(secondIdx).toBeGreaterThan(firstIdx);
+    expect(lines.slice(firstIdx + 1, secondIdx)).toContain('>');
+  });
+
+  test('treats .. cnote:: as a custom admonition with :caption: support', () => {
+    const withCaption = rstToMarkdown([
+      '.. cnote::',
+      '   :caption: 说明',
+      '',
+      '   Body content here.',
+    ].join('\n'));
+
+    expect(withCaption).toContain('> **说明**');
+    expect(withCaption).toContain('> Body content here.');
+    expect(withCaption).not.toContain(':caption:');
+    expect(withCaption).not.toContain('> **Cnote**');
+
+    const withoutCaption = rstToMarkdown([
+      '.. cnote::',
+      '',
+      '   Default label fallback.',
+    ].join('\n'));
+
+    expect(withoutCaption).toContain('> **Cnote**');
+    expect(withoutCaption).toContain('> Default label fallback.');
+  });
+
+  test('renders line blocks (| prefixed lines) as a blockquote with hard breaks', () => {
+    const md = rstToMarkdown([
+      'Intro paragraph.',
+      '',
+      '  | First poetic line.',
+      '  | Second poetic line.',
+      '  | Third with ``code``.',
+      '',
+      'Trailing paragraph.',
+    ].join('\n'));
+
+    expect(md).toContain('> First poetic line.  ');
+    expect(md).toContain('> Second poetic line.  ');
+    expect(md).toContain('> Third with `code`.');
+    expect(md).not.toContain('| First');
+    const lines = md.split('\n');
+    const last = lines.findIndex((l) => l.startsWith('> Third'));
+    expect(last).toBeGreaterThan(-1);
+    expect(lines[last].endsWith('  ')).toBe(false);
+  });
+
+  test('renders :doc: cross-references and works alongside escaped whitespace', () => {
+    const md = rstToMarkdown([
+      '前面提到的\\ :doc:`AI编程中人的作用`\\ 这件事。',
+      '',
+      'See :doc:`Label <some/path>` for details.',
+    ].join('\n'));
+
+    expect(md).toContain('前面提到的[AI编程中人的作用](AI编程中人的作用)这件事。');
+    expect(md).toContain('[Label](some/path)');
+    expect(md).not.toContain(':doc:');
+    expect(md).not.toContain('\\ ');
+  });
+
+  test('renders :ref: and :numref: roles as anchor links', () => {
+    const md = rstToMarkdown([
+      'See :ref:`s_extension` for details.',
+      '',
+      'Look at :ref:`扩展机制 <s_extension>`.',
+      '',
+      'Per :numref:`图%s <图：架构图>` above.',
+      '',
+      'Bare :numref:`图：架构图` works too.',
+    ].join('\n'));
+
+    expect(md).toContain('[s_extension](#s_extension)');
+    expect(md).toContain('[扩展机制](#s_extension)');
+    expect(md).toContain('[图](#图架构图)');
+    expect(md).toContain('[图：架构图](#图架构图)');
+  });
+
+  test('suppresses .. toctree:: directive and its child list from rendered body', () => {
+    const markdown = rstToMarkdown([
+      'Intro paragraph.',
+      '',
+      '.. toctree::',
+      '   :maxdepth: 2',
+      '',
+      '   first-child',
+      '   second-child',
+      '',
+      'Trailing paragraph.',
+    ].join('\n'));
+
+    expect(markdown).toContain('Intro paragraph.');
+    expect(markdown).toContain('Trailing paragraph.');
+    expect(markdown).not.toContain('toctree');
+    expect(markdown).not.toContain('first-child');
+    expect(markdown).not.toContain('second-child');
+    expect(markdown).not.toContain(':maxdepth:');
+  });
+
+  test('normalizes rST escaped whitespace inline', () => {
+    const doc = parseRstDocument([
+      'Title',
+      '=====',
+      '',
+      '前面提到的\\ ``code``\\ 这件事。',
+    ].join('\n'));
+
+    expect(doc.markdownBody).toContain('前面提到的`code`这件事。');
+    expect(doc.markdownBody).not.toContain('\\ ');
+  });
+
   test('ignores unknown metadata fields and rejects malformed supported values', () => {
     const ignored = parseRstDocument([
       'Title',

package/src/lib/rst.ts

@@ -36,7 +36,8 @@ export interface ParsedRstDocument {
   metadata: RstMetadata;
   headings: RstHeading[];
   excerpt: string;
-  readingTime: string;
+  readingMinutes: number;
+  wordCount: number;
 }
 
 export class RstParseError extends Error {
@@ -287,9 +288,44 @@ function mergeMetadata(base: RstMetadata, override: RstMetadata): RstMetadata {
   };
 }
 
+function slugifyAnchor(target: string): string {
+  return new GithubSlugger().slug(target.trim());
+}
+
 function convertInlineRst(text: string): string {
   return text
+    .replace(/\\([ \t])/g, '')
     .replace(/``([^`]+)``/g, '`$1`')
+    .replace(
+      /:ref:`([^<`]+?)\s*<([^>`]+)>`/g,
+      (_, title: string, target: string) => `[${title.trim()}](#${slugifyAnchor(target)})`,
+    )
+    .replace(
+      /:ref:`([^`]+)`/g,
+      (_, target: string) => `[${target.trim()}](#${slugifyAnchor(target)})`,
+    )
+    .replace(
+      /:numref:`([^<`]+?)\s*<([^>`]+)>`/g,
+      (_, title: string, target: string) => {
+        const label = title.replace(/%s/g, '').trim() || target.trim();
+        return `[${label}](#${slugifyAnchor(target)})`;
+      },
+    )
+    .replace(
+      /:numref:`([^`]+)`/g,
+      (_, target: string) => `[${target.trim()}](#${slugifyAnchor(target)})`,
+    )
+    .replace(
+      /:doc:`([^<`]+?)\s*<([^>`]+)>`/g,
+      (_, title: string, target: string) => `[${title.trim()}](${target.trim()})`,
+    )
+    .replace(
+      /:doc:`([^`]+)`/g,
+      (_, target: string) => {
+        const trimmed = target.trim();
+        return `[${trimmed}](${trimmed})`;
+      },
+    )
     .replace(/`([^`]+?)\s*<([^>]+)>`__/g, '[$1]($2)')
     .replace(/`([^`]+?)\s*<([^>]+)>`_/g, '[$1]($2)');
 }
@@ -301,6 +337,73 @@ function detectHeadingLevel(adornment: string): number | null {
   return null;
 }
 
+interface DirectiveCodeOptions {
+  language?: string;
+  caption?: string;
+  linenos?: boolean;
+  emphasizeLines?: string;
+  label?: string;
+}
+
+function readDirectiveOptions(
+  lines: string[],
+  startIndex: number,
+): { options: DirectiveCodeOptions; nextLine: number } {
+  const options: DirectiveCodeOptions = {};
+  let i = startIndex;
+  while (i < lines.length) {
+    const match = lines[i].match(/^\s+:([A-Za-z-]+):\s*(.*)$/);
+    if (!match) break;
+    const key = match[1].toLowerCase();
+    const value = match[2].trim();
+    if (key === 'language') options.language = value;
+    else if (key === 'caption') options.caption = value;
+    else if (key === 'linenos') options.linenos = true;
+    else if (key === 'emphasize-lines') options.emphasizeLines = value;
+    else if (key === 'label') options.label = value;
+    i++;
+  }
+  // Skip the blank line separator that always follows the option block.
+  while (i < lines.length && !lines[i].trim()) i++;
+  return { options, nextLine: i };
+}
+
+function buildFenceMetaFromOptions(options: DirectiveCodeOptions): string[] {
+  const meta: string[] = [];
+  // [label] must be the FIRST token after the language for the MDX-side
+  // parseFenceMeta + remark-code-group plugin to pick it up.
+  if (options.label) meta.push(`[${options.label}]`);
+  if (options.caption) meta.push(`title="${options.caption.replace(/"/g, '\\"')}"`);
+  if (options.linenos) meta.push('linenos');
+  if (options.emphasizeLines) meta.push(`{${options.emphasizeLines}}`);
+  return meta;
+}
+
+function convertNestedCodeBlocksToFences(body: string[]): string[] {
+  // Used by the .. code-group:: fallback path. Walks the indented body lines
+  // (already dedented to the directive's body indent) and emits Markdown
+  // fences for each nested .. code-block:: child. Anything else is dropped
+  // since :::code-group expects only code fences as children.
+  const out: string[] = [];
+  for (let i = 0; i < body.length; i++) {
+    const line = body[i];
+    const match = line.match(/^\.\.\s+(?:code-block|code|sourcecode)::\s*([A-Za-z0-9_+-]+)?\s*$/);
+    if (!match) continue;
+    const directiveLanguage = match[1] ?? '';
+    const { options, nextLine } = readDirectiveOptions(body, i + 1);
+    const { content, nextIndex } = readIndentedBlock(body, nextLine);
+    const language = options.language || directiveLanguage;
+    const fenceMeta = buildFenceMetaFromOptions(options);
+    const infoString = [language, ...fenceMeta].filter(Boolean).join(' ');
+    out.push(`\`\`\`${infoString}`.trimEnd());
+    out.push(...content);
+    out.push('```');
+    out.push('');
+    i = nextIndex - 1;
+  }
+  return out;
+}
+
 function readIndentedBlock(lines: string[], startIndex: number): { content: string[]; nextIndex: number } {
   let i = startIndex;
   while (i < lines.length && !lines[i].trim()) i++;
@@ -358,7 +461,79 @@ export function rstToMarkdown(body: string): string {
       }
     }
 
-    const imageMatch = line.match(/^\.\.\s+image::\s+(.+?)\s*$/);
+    if (/^\.\.\s+toctree::\s*$/.test(line)) {
+      const { nextIndex } = readIndentedBlock(lines, i + 1);
+      i = nextIndex - 1;
+      continue;
+    }
+
+    const lineBlockRegex = /^\s*\|(?:\s(.*))?$/;
+    if (lineBlockRegex.test(line)) {
+      const blockLines: string[] = [];
+      let j = i;
+      while (j < lines.length) {
+        const lineMatch = lines[j].match(lineBlockRegex);
+        if (!lineMatch) break;
+        blockLines.push((lineMatch[1] ?? '').trim());
+        j++;
+      }
+      out.push('');
+      blockLines.forEach((bl, idx) => {
+        const content = convertInlineRst(bl);
+        const isLast = idx === blockLines.length - 1;
+        out.push(isLast ? `> ${content}` : `> ${content}  `);
+      });
+      out.push('');
+      i = j - 1;
+      continue;
+    }
+
+    const admonitionMatch = line.match(
+      /^\.\.\s+(note|warning|tip|caution|attention|important|hint|danger|error|cnote)::(?:\s+(.*\S))?\s*$/i,
+    );
+    if (admonitionMatch) {
+      const kind = admonitionMatch[1].toLowerCase();
+      const inlineBody = admonitionMatch[2]?.trim() ?? '';
+      const { content, nextIndex } = readIndentedBlock(lines, i + 1);
+
+      let captionLabel: string | null = null;
+      let bodyStart = 0;
+      if (!inlineBody) {
+        while (bodyStart < content.length && content[bodyStart].trim() === '') bodyStart++;
+        while (bodyStart < content.length) {
+          const ln = content[bodyStart];
+          if (ln.trim() === '') {
+            bodyStart++;
+            break;
+          }
+          const optionMatch = ln.match(/^\s*:([A-Za-z-]+):\s*(.*)$/);
+          if (!optionMatch) break;
+          if (optionMatch[1].toLowerCase() === 'caption') {
+            captionLabel = optionMatch[2].trim();
+          }
+          bodyStart++;
+        }
+      }
+      const inlineHasParagraphBreak =
+        inlineBody && i + 1 < lines.length && lines[i + 1].trim() === '';
+      const bodyContent = inlineBody
+        ? inlineHasParagraphBreak
+          ? [inlineBody, '', ...content.slice(bodyStart)]
+          : [inlineBody, ...content.slice(bodyStart)]
+        : content.slice(bodyStart);
+
+      const label = captionLabel || (kind.charAt(0).toUpperCase() + kind.slice(1));
+      out.push(`> **${label}**`);
+      out.push('>');
+      for (const ln of bodyContent) {
+        out.push(ln.trim() === '' ? '>' : `> ${convertInlineRst(ln)}`);
+      }
+      out.push('');
+      i = nextIndex - 1;
+      continue;
+    }
+
+    const imageMatch = line.match(/^\.\.\s+(?:image|figure)::\s+(.+?)\s*$/);
     if (imageMatch) {
       let alt = '';
       let j = i + 1;
@@ -376,10 +551,30 @@ export function rstToMarkdown(body: string): string {
       continue;
     }
 
-    const codeMatch = line.match(/^\.\.\s+(?:code-block|code)::\s*([A-Za-z0-9_-]+)?\s*$/);
+    const codeGroupMatch = line.match(/^\.\.\s+code-group::\s*$/);
+    if (codeGroupMatch) {
+      // Collect the indented body — nested .. code-block:: blocks — and emit a
+      // :::code-group MDX directive so the result lands in the same MDX pipeline.
+      const { content: groupBody, nextIndex } = readIndentedBlock(lines, i + 1);
+      out.push(':::code-group');
+      out.push(...convertNestedCodeBlocksToFences(groupBody));
+      out.push(':::');
+      out.push('');
+      i = nextIndex - 1;
+      continue;
+    }
+
+    const codeMatch = line.match(/^\.\.\s+(?:code-block|code|sourcecode)::\s*([A-Za-z0-9_+-]+)?\s*$/);
     if (codeMatch) {
-      const { content, nextIndex } = readIndentedBlock(lines, i + 1);
-      out.push(`\`\`\`${codeMatch[1] ?? ''}`.trimEnd());
+      const directiveLanguage = codeMatch[1] ?? '';
+      const { options, nextLine } = readDirectiveOptions(lines, i + 1);
+      const { content, nextIndex } = readIndentedBlock(lines, nextLine);
+
+      const language = options.language || directiveLanguage;
+      const fenceMeta = buildFenceMetaFromOptions(options);
+
+      const infoString = [language, ...fenceMeta].filter(Boolean).join(' ');
+      out.push(`\`\`\`${infoString}`.trimEnd());
       out.push(...content);
       out.push('```');
       out.push('');
@@ -415,10 +610,17 @@ export function rstToMarkdown(body: string): string {
   return out.join('\n').trim();
 }
 
-function calculateReadingTime(content: string): string {
+function calculateReadingMinutes(content: string): number {
   const wordsPerMinute = 200;
   const hanCharsPerMinute = 300;
+  const { latinWords, hanChars } = countRstTokens(content);
+  const estimatedMinutes = (latinWords / wordsPerMinute) + (hanChars / hanCharsPerMinute);
+  return Math.max(1, Math.ceil(estimatedMinutes));
+}
 
+// Shared token counter — both reading-minutes and word-count need the same
+// view of what counts as a word so they never disagree on the same input.
+function countRstTokens(content: string): { latinWords: number; hanChars: number } {
   const text = content
     .replace(/<\/?[^>]+(>|$)/g, '')
     .replace(/```[\s\S]*?```/g, '')
@@ -426,13 +628,14 @@ function calculateReadingTime(content: string): string {
     .replace(/!\[[^\]]*\]\([^)]+\)/g, '')
     .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
     .replace(/[#*_~>\-[\]()]/g, ' ');
+  const hanChars = (text.match(/[\u3400-\u4DBF\u4E00-\u9FFF\uF900-\uFAFF]/g) || []).length;
+  const latinWords = (text.match(/[A-Za-z0-9]+(?:['\u2019-][A-Za-z0-9]+)*/g) || []).length;
+  return { latinWords, hanChars };
+}
 
-  const hanCharCount = (text.match(/[\u3400-\u4DBF\u4E00-\u9FFF\uF900-\uFAFF]/g) || []).length;
-  const latinWordCount = (text.match(/[A-Za-z0-9]+(?:['’-][A-Za-z0-9]+)*/g) || []).length;
-
-  const estimatedMinutes = (latinWordCount / wordsPerMinute) + (hanCharCount / hanCharsPerMinute);
-  const minutes = Math.max(1, Math.ceil(estimatedMinutes));
-  return `${minutes} min read`;
+function calculateWordCount(content: string): number {
+  const { latinWords, hanChars } = countRstTokens(content);
+  return latinWords + hanChars;
 }
 
 function getHeadings(content: string): RstHeading[] {
@@ -465,6 +668,7 @@ export function parseRstDocument(source: string): ParsedRstDocument {
     metadata,
     headings: getHeadings(markdownBody),
     excerpt: metadata.excerpt ?? '',
-    readingTime: calculateReadingTime(markdownBody),
+    readingMinutes: calculateReadingMinutes(markdownBody),
+    wordCount: calculateWordCount(markdownBody),
   };
 }