@hutusi/amytis 1.15.0 → 1.17.0

package/src/lib/remark-book-chapter-links.ts

@@ -0,0 +1,106 @@
+import { visit } from 'unist-util-visit';
+import type { Root, Link } from 'mdast';
+import path from 'path';
+import { getBookChapterUrl } from './urls';
+
+export interface BookChapterLinksOptions {
+  /** Slug of the book being rendered (passed to getBookChapterUrl). */
+  bookSlug: string;
+  /** Absolute path to the book directory (e.g. content/books/dmla). */
+  bookDir: string;
+  /** Absolute path of the chapter source file (e.g. content/books/dmla/maths/linear/introduction.md). */
+  chapterSourcePath: string;
+  /** Set of valid chapter ids for the book — used to validate link targets. */
+  validChapterIds: ReadonlySet<string>;
+}
+
+const EXTERNAL_RE = /^(?:https?:|mailto:|tel:|ftp:|\/\/|#)/i;
+const MD_LINK_RE = /\.(?:md|mdx)(?:#([^?]*))?$/i;
+
+/**
+ * Rewrites relative `.md` / `.mdx` links in a book chapter to canonical
+ * `/books/<slug>/<chapter-id>/[#fragment]` URLs, so the cross-references that
+ * exist in a VuePress source repo (where chapters live in nested folders and
+ * link to each other via `[向量](vectors.md)` or `[张量](matrices.md#张量)`)
+ * keep working after the content is imported flat into Amytis's book layout.
+ *
+ * Resolution strategy
+ * ───────────────────
+ * - Skip external links (http, mailto, //, hash-only).
+ * - Strip an optional `#fragment` suffix; remember it for re-attachment.
+ * - Resolve the remaining path relative to `chapterSourcePath`'s directory.
+ * - Make the result relative to `bookDir`, drop the `.md`/`.mdx` extension,
+ *   and treat the resulting POSIX path as the chapter id.
+ * - Validate the id against `validChapterIds`.
+ *   - If the link escapes the book directory, **throw** — that's almost
+ *     always a real bug (typo in `../../../somewhere`).
+ *   - If the chapter id is well-formed but not in the TOC (e.g. the author
+ *     links to a chapter they haven't written yet, or that's commented out
+ *     of the sidebar), **warn and leave the link unrewritten** instead of
+ *     blocking the build. Matches the Shiki precedent in CLAUDE.md: a
+ *     single broken cross-reference shouldn't fail a production deploy.
+ *     The warning still surfaces in CI build logs.
+ */
+const warned = new Set<string>();
+export default function remarkBookChapterLinks(options: BookChapterLinksOptions) {
+  const { bookSlug, bookDir, chapterSourcePath, validChapterIds } = options;
+  const chapterDir = path.dirname(chapterSourcePath);
+  const bookDirResolved = path.resolve(bookDir);
+
+  return (tree: Root) => {
+    visit(tree, 'link', (node: Link) => {
+      const url = node.url;
+      if (!url || EXTERNAL_RE.test(url)) return;
+      const match = MD_LINK_RE.exec(url);
+      if (!match) return;
+
+      // Split fragment from path.
+      const hashIdx = url.indexOf('#');
+      const fragment = hashIdx >= 0 ? url.slice(hashIdx + 1) : '';
+      const pathPart = hashIdx >= 0 ? url.slice(0, hashIdx) : url;
+
+      // Resolve to absolute, then back to a bookDir-relative POSIX path.
+      // decodeURIComponent throws URIError on malformed `%XX`; swallow that
+      // and fall back to the raw string so a single broken percent-encoded
+      // link doesn't 500 the build (matches the broader "warn don't throw"
+      // posture for stale cross-references below).
+      let decodedPath: string;
+      try {
+        decodedPath = decodeURIComponent(pathPart);
+      } catch {
+        decodedPath = pathPart;
+      }
+      const resolvedAbs = path.resolve(chapterDir, decodedPath);
+      const inside =
+        resolvedAbs === bookDirResolved ||
+        resolvedAbs.startsWith(bookDirResolved + path.sep);
+      if (!inside) {
+        throw new Error(
+          `[amytis] Book chapter link "${url}" in ${chapterSourcePath} resolves ` +
+          `outside the book directory ${bookDirResolved}. Cross-book links are not supported.`
+        );
+      }
+
+      const rel = path.relative(bookDirResolved, resolvedAbs).split(path.sep).join('/');
+      const chapterId = rel.replace(/\.(?:md|mdx)$/i, '').replace(/\/index$/i, '');
+
+      if (!validChapterIds.has(chapterId)) {
+        const warnKey = `${bookSlug}::${chapterId}`;
+        if (!warned.has(warnKey)) {
+          warned.add(warnKey);
+          console.warn(
+            `[amytis] Book chapter link "${url}" in ${chapterSourcePath} points to ` +
+            `chapter id "${chapterId}", which is not in book "${bookSlug}"'s TOC. ` +
+            `Leaving link unrewritten — it will 404 if clicked. To fix, add the ` +
+            `chapter to index.mdx or remove the link.`
+          );
+        }
+        return;
+      }
+
+      node.url = fragment
+        ? `${getBookChapterUrl(bookSlug, chapterId)}#${fragment}`
+        : getBookChapterUrl(bookSlug, chapterId);
+    });
+  };
+}

package/src/lib/remark-code-group.ts

@@ -0,0 +1,54 @@
+import { visit } from 'unist-util-visit';
+import type { Root, Code } from 'mdast';
+import { parseFenceMeta } from './shiki';
+
+interface ContainerDirective {
+  type: 'containerDirective';
+  name: string;
+  children: Array<Code | { type: string }>;
+  data?: { hName?: string; hProperties?: Record<string, unknown> };
+}
+
+let counter = 0;
+function nextGroupId(): string {
+  counter += 1;
+  return `cg${counter.toString(36)}`;
+}
+
+/**
+ * Transforms `:::code-group ... :::` container directives into a custom hast
+ * element <code-group data-labels="[...]" data-group-id="..."> whose children
+ * are the original fenced code blocks (still processed by the normal `code`
+ * override and Shiki pipeline). The component override for `code-group` is
+ * <CodeGroup>, which renders the radio+label tabs HTML.
+ *
+ * Labels come from the Docusaurus-style `[label]` token at the start of each
+ * fence's meta (e.g. ```bash [npm]). Falls back to the language name when
+ * absent, then to "Tab N" when both are missing.
+ */
+export default function remarkCodeGroup() {
+  return (tree: Root) => {
+    visit(tree, (node) => {
+      if (node.type !== 'containerDirective') return;
+      const directive = node as unknown as ContainerDirective;
+      if (directive.name !== 'code-group') return;
+
+      const labels: string[] = [];
+      let tabIndex = 0;
+      for (const child of directive.children) {
+        if (child.type !== 'code') continue;
+        const code = child as Code;
+        const parsed = parseFenceMeta(code.meta ?? undefined);
+        tabIndex += 1;
+        labels.push(parsed.tabLabel ?? code.lang ?? `Tab ${tabIndex}`);
+      }
+
+      directive.data = directive.data ?? {};
+      directive.data.hName = 'code-group';
+      directive.data.hProperties = {
+        'data-labels': JSON.stringify(labels),
+        'data-group-id': nextGroupId(),
+      };
+    });
+  };
+}

package/src/lib/remark-github-alerts.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, test } from 'bun:test';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import type { Root, Blockquote } from 'mdast';
+import remarkGithubAlerts from './remark-github-alerts';
+
+function parse(markdown: string): Root {
+  return unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkGithubAlerts)
+    .runSync(unified().use(remarkParse).parse(markdown)) as Root;
+}
+
+function findBlockquote(tree: Root): Blockquote | undefined {
+  return tree.children.find((n): n is Blockquote => n.type === 'blockquote');
+}
+
+describe('remarkGithubAlerts', () => {
+  test('transforms [!NOTE] blockquote into a github-alert hast element', () => {
+    const tree = parse('> [!NOTE]\n> body content');
+    const bq = findBlockquote(tree);
+    const data = bq?.data as { hName?: string; hProperties?: Record<string, unknown> } | undefined;
+    expect(data?.hName).toBe('github-alert');
+    expect(data?.hProperties?.['data-alert-type']).toBe('note');
+  });
+
+  test.each(['NOTE', 'TIP', 'IMPORTANT', 'WARNING', 'CAUTION'])(
+    'matches [!%s] case-sensitively (uppercase) and lowercases the type',
+    (typeUpper) => {
+      const tree = parse(`> [!${typeUpper}]\n> body`);
+      const bq = findBlockquote(tree);
+      const data = bq?.data as { hProperties?: Record<string, unknown> } | undefined;
+      expect(data?.hProperties?.['data-alert-type']).toBe(typeUpper.toLowerCase());
+    },
+  );
+
+  test('matches lowercase [!note] too (GitHub is case-insensitive)', () => {
+    const tree = parse('> [!note]\n> body');
+    const bq = findBlockquote(tree);
+    const data = bq?.data as { hProperties?: Record<string, unknown> } | undefined;
+    expect(data?.hProperties?.['data-alert-type']).toBe('note');
+  });
+
+  test('does not transform [!UNKNOWN] blockquotes — they stay as plain blockquotes', () => {
+    const tree = parse('> [!UNKNOWN]\n> body');
+    const bq = findBlockquote(tree);
+    expect(bq?.data).toBeUndefined();
+  });
+
+  test('does not transform plain blockquotes without a marker', () => {
+    const tree = parse('> just a quote\n> with two lines');
+    const bq = findBlockquote(tree);
+    expect(bq?.data).toBeUndefined();
+  });
+
+  test('strips the marker token from the body content', () => {
+    const tree = parse('> [!NOTE]\n> the surviving body');
+    const bq = findBlockquote(tree);
+    // After the plugin runs, the marker should be gone from the first text node.
+    const first = bq?.children[0];
+    if (first?.type !== 'paragraph') throw new Error('expected paragraph');
+    const text = first.children[0];
+    if (text?.type !== 'text') throw new Error('expected text');
+    expect(text.value).not.toMatch(/\[!NOTE\]/);
+    expect(text.value).toContain('the surviving body');
+  });
+
+  test('handles inline content on the same line as the marker', () => {
+    // GitHub's spec technically wants [!TYPE] on its own line, but some authors
+    // write `> [!NOTE] body inline`. We accept it.
+    const tree = parse('> [!NOTE] inline body');
+    const bq = findBlockquote(tree);
+    const data = bq?.data as { hProperties?: Record<string, unknown> } | undefined;
+    expect(data?.hProperties?.['data-alert-type']).toBe('note');
+    const first = bq?.children[0];
+    if (first?.type !== 'paragraph') throw new Error('expected paragraph');
+    const text = first.children[0];
+    if (text?.type !== 'text') throw new Error('expected text');
+    expect(text.value).toContain('inline body');
+  });
+});

package/src/lib/remark-github-alerts.ts

@@ -0,0 +1,65 @@
+import { visit } from 'unist-util-visit';
+import type { Root, Blockquote, Paragraph, Text } from 'mdast';
+
+const ALERT_TYPES = ['note', 'tip', 'important', 'warning', 'caution'] as const;
+type AlertType = (typeof ALERT_TYPES)[number];
+
+// Match `[!TYPE]` (case-insensitive per GitHub) at the start of the first text
+// node, optionally followed by inline content on the same line.
+const MARKER_RE = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*/i;
+
+/**
+ * Transforms `> [!NOTE]` / `> [!TIP]` / `> [!IMPORTANT]` / `> [!WARNING]` /
+ * `> [!CAUTION]` blockquotes (GitHub-flavored alerts) into a custom hast
+ * element `<github-alert data-alert-type="note">` whose children are the
+ * remaining blockquote content. `remark-gfm` v4 does not include this
+ * transform — alerts pass through as plain blockquotes without this plugin.
+ *
+ * The component override for `github-alert` is `<GithubAlert>`, which renders
+ * the styled callout with an icon, title, and body.
+ */
+export default function remarkGithubAlerts() {
+  return (tree: Root) => {
+    visit(tree, 'blockquote', (node: Blockquote) => {
+      if (node.children.length === 0) return;
+      const firstBlock = node.children[0];
+      if (firstBlock.type !== 'paragraph') return;
+      const paragraph = firstBlock as Paragraph;
+      if (paragraph.children.length === 0) return;
+      const firstText = paragraph.children[0];
+      if (firstText.type !== 'text') return;
+
+      const text = firstText as Text;
+      const match = text.value.match(MARKER_RE);
+      if (!match) return;
+
+      const type = match[1].toLowerCase() as AlertType;
+      // Strip the marker token from the first text node. If the rest of that
+      // text node was just the marker (now empty), shift it out AND drop any
+      // immediately-following soft-break so the body doesn't start with a
+      // blank line.
+      const trailing = text.value.slice(match[0].length).replace(/^\n+/, '');
+      if (trailing) {
+        text.value = trailing;
+      } else {
+        paragraph.children.shift();
+        if (paragraph.children[0]?.type === 'break') {
+          paragraph.children.shift();
+        }
+        // If the first paragraph is now entirely empty, drop it altogether.
+        if (paragraph.children.length === 0) {
+          node.children.shift();
+        }
+      }
+
+      node.data = node.data ?? {};
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (node.data as any).hName = 'github-alert';
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (node.data as any).hProperties = { 'data-alert-type': type };
+    });
+  };
+}
+
+export { ALERT_TYPES };
+export type { AlertType };

package/src/lib/remark-vuepress-containers.ts

@@ -0,0 +1,130 @@
+import { visit } from 'unist-util-visit';
+import type { Root } from 'mdast';
+
+const CONTAINER_OPENER_RE = /^:::[ \t]+([a-zA-Z][\w-]*)(?:[ \t]+([^\n]+))?[ \t]*$/;
+const FENCE_OPEN_RE = /^[ \t]*(`{3,}|~{3,})/;
+
+function normalizeContainerLine(line: string): string {
+  return line.replace(
+    CONTAINER_OPENER_RE,
+    (_match, name: string, label: string | undefined) =>
+      label ? `:::${name}[${label.trim()}]` : `:::${name}`,
+  );
+}
+
+/**
+ * Pre-process VuePress's relaxed container opener (`::: name [optional title]`)
+ * into remark-directive's canonical form (`:::name[title]`). The Markdown spec
+ * variant remark-directive recognizes is space-less; the dmla source — and
+ * VuePress in general — uses a space-after-colons style with an inline title.
+ *
+ * Skips fenced code blocks (`` ``` `` / `~~~`) so a documentation example that
+ * shows VuePress container syntax verbatim doesn't get rewritten as if it were
+ * the syntax itself. The fence tracker is character-type-aware: a `~~~` fence
+ * isn't closed by `` ``` `` and vice-versa, matching CommonMark.
+ *
+ * Runs as a string-level pass before the AST is built, so the existing
+ * `:::code-group` usage already in this repo (no space) is unaffected.
+ */
+export function normalizeVuepressContainerSyntax(source: string): string {
+  const lines = source.split('\n');
+  const out: string[] = [];
+  let openFence: string | null = null;
+
+  for (const line of lines) {
+    if (openFence === null) {
+      const openMatch = line.match(FENCE_OPEN_RE);
+      if (openMatch) {
+        openFence = openMatch[1];
+        out.push(line);
+        continue;
+      }
+      out.push(normalizeContainerLine(line));
+    } else {
+      // A closing fence is one with the same character type and at least as
+      // many characters as the opener, optionally indented, with nothing after.
+      const closeRe = new RegExp(`^[ \\t]*${openFence[0]}{${openFence.length},}\\s*$`);
+      if (closeRe.test(line)) openFence = null;
+      out.push(line);
+    }
+  }
+  return out.join('\n');
+}
+
+// VuePress container names → GitHub-flavored alert types. Maps the four
+// container types the dmla source uses (note/tip/warning/danger). `info` and
+// `caution` are accepted as VuePress synonyms; `danger` rewrites to GitHub's
+// `caution` since GitHub doesn't have a `danger` variant.
+const CONTAINER_TO_ALERT: Record<string, string> = {
+  note: 'note',
+  info: 'note',
+  tip: 'tip',
+  important: 'important',
+  warning: 'warning',
+  caution: 'caution',
+  danger: 'caution',
+};
+
+interface DirectiveLike {
+  type: string;
+  name?: string;
+  attributes?: Record<string, string | undefined> | null;
+  children?: unknown[];
+  data?: { hName?: string; hProperties?: Record<string, unknown> };
+}
+
+interface DirectiveLabelNode {
+  type: 'paragraph';
+  data?: { directiveLabel?: boolean };
+  children: Array<{ type: string; value?: string }>;
+}
+
+/**
+ * Transforms VuePress-style container directives (`:::note`, `:::tip`,
+ * `:::warning`, `:::danger`, `:::info`) into the same custom hast element
+ * (`<github-alert data-alert-type="..." data-alert-title="...">`) that
+ * `remark-github-alerts` emits. Keeping a single component for both syntaxes
+ * means the renderer doesn't need to learn a second callout shape.
+ *
+ * `remark-directive` must run before this plugin so the `containerDirective`
+ * nodes exist in the tree.
+ *
+ * A custom title (e.g. `:::tip 智慧的疆界`) is preserved on the
+ * `data-alert-title` attribute. The remark-directive parser surfaces the
+ * label as the first child paragraph with `data.directiveLabel === true`.
+ */
+export default function remarkVuepressContainers() {
+  return (tree: Root) => {
+    visit(tree, (node: unknown) => {
+      const directive = node as DirectiveLike;
+      if (directive.type !== 'containerDirective') return;
+      const name = directive.name?.toLowerCase();
+      if (!name || !(name in CONTAINER_TO_ALERT)) return;
+
+      // Extract an optional title from the first child paragraph marked as
+      // the directive label. (remark-directive puts `data.directiveLabel: true`
+      // on the synthetic paragraph it builds from text following the directive
+      // name on the opening line.)
+      let title: string | undefined;
+      if (directive.children && directive.children.length > 0) {
+        const first = directive.children[0] as DirectiveLabelNode;
+        if (first?.type === 'paragraph' && first.data?.directiveLabel) {
+          title = first.children
+            .filter(c => c.type === 'text')
+            .map(c => c.value ?? '')
+            .join('')
+            .trim() || undefined;
+          directive.children.shift();
+        }
+      }
+
+      directive.data = directive.data ?? {};
+      directive.data.hName = 'github-alert';
+      const hProperties: Record<string, unknown> = {
+        'data-alert-type': CONTAINER_TO_ALERT[name],
+      };
+      if (title) hProperties['data-alert-title'] = title;
+      directive.data.hProperties = hProperties;
+    });
+  };
+}

package/src/lib/rst-renderer.ts

@@ -34,7 +34,8 @@ export interface RenderedRstDocument {
   headings: PythonRstHeading[];
   metadata: RstMetadata;
   excerpt: string;
-  readingTime: string;
+  readingMinutes: number;
+  wordCount: number;
   assets: PythonRstAsset[];
   warnings: string[];
 }
@@ -67,7 +68,10 @@ interface RstRendererDiskCacheEntry {
 
 const rstRenderCache = new Map<string, RenderedRstDocument>();
 const PYTHON_RENDERER_MAX_BUFFER = 1024 * 1024 * 128;
-const RST_RENDERER_DISK_CACHE_VERSION = '1';
+// Bumped when the docutils renderer's HTML output shape changes:
+// v2 emitted <pre data-amytis-code> markers; v3 additionally emits
+// <div data-amytis-code-group> wrappers around .. code-group:: nests.
+const RST_RENDERER_DISK_CACHE_VERSION = '3';
 const rstRendererCacheDir = path.join(process.cwd(), '.cache', 'rst-renderer');
 let resolvedPythonCommandSpec: PythonCommandSpec | null = null;
 let pythonRendererInvocationCount = 0;
@@ -345,15 +349,21 @@ export function normalizePythonRstMetadata(metadata: Record<string, unknown>): R
   return normalized;
 }
 
-function calculateReadingTimeFromText(text: string): string {
+function calculateReadingMinutesFromText(text: string): number {
   const wordsPerMinute = 200;
   const hanCharsPerMinute = 300;
 
   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 latinWordCount = (text.match(/[A-Za-z0-9]+(?:['\u2019-][A-Za-z0-9]+)*/g) || []).length;
 
   const estimatedMinutes = (latinWordCount / wordsPerMinute) + (hanCharCount / hanCharsPerMinute);
-  return `${Math.max(1, Math.ceil(estimatedMinutes))} min read`;
+  return Math.max(1, Math.ceil(estimatedMinutes));
+}
+
+function calculateWordCountFromText(text: string): number {
+  const hanCharCount = (text.match(/[\u3400-\u4DBF\u4E00-\u9FFF\uF900-\uFAFF]/g) || []).length;
+  const latinWordCount = (text.match(/[A-Za-z0-9]+(?:['\u2019-][A-Za-z0-9]+)*/g) || []).length;
+  return latinWordCount + hanCharCount;
 }
 
 export function validatePythonRstResult(result: PythonRstRenderResult, filePath: string): void {
@@ -554,7 +564,8 @@ export function renderRstFile(filePath: string, imageBaseSlug: string): Rendered
     headings: result.headings,
     metadata,
     excerpt: metadata.excerpt ?? '',
-    readingTime: calculateReadingTimeFromText(result.text),
+    readingMinutes: calculateReadingMinutesFromText(result.text),
+    wordCount: calculateWordCountFromText(result.text),
     assets: result.assets ?? [],
     warnings: (result.warnings ?? []).map((warning) => String(warning)),
   };
@@ -604,7 +615,8 @@ export function renderRstFilesBatch(entries: PythonRstBatchEntry[]): Map<string,
       headings: result.headings,
       metadata,
       excerpt: metadata.excerpt ?? '',
-      readingTime: calculateReadingTimeFromText(result.text),
+      readingMinutes: calculateReadingMinutesFromText(result.text),
+      wordCount: calculateWordCountFromText(result.text),
       assets: result.assets ?? [],
       warnings: (result.warnings ?? []).map((warning) => String(warning)),
     };