@hutusi/amytis 1.14.0 → 1.16.0

package/src/lib/rst.ts

@@ -0,0 +1,674 @@
+import GithubSlugger from 'github-slugger';
+
+export interface RstHeading {
+  id: string;
+  text: string;
+  level: number;
+}
+
+export interface RstMetadata {
+  date?: string;
+  subtitle?: string;
+  excerpt?: string;
+  category?: string;
+  tags?: string[];
+  authors?: string[];
+  author?: string;
+  layout?: string;
+  series?: string;
+  coverImage?: string;
+  sort?: 'date-desc' | 'date-asc' | 'manual';
+  posts?: string[];
+  featured?: boolean;
+  pinned?: boolean;
+  draft?: boolean;
+  latex?: boolean;
+  toc?: boolean;
+  commentable?: boolean;
+  redirectFrom?: string[];
+  type?: 'collection';
+}
+
+export interface ParsedRstDocument {
+  title: string;
+  body: string;
+  markdownBody: string;
+  metadata: RstMetadata;
+  headings: RstHeading[];
+  excerpt: string;
+  readingMinutes: number;
+  wordCount: number;
+}
+
+export class RstParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RstParseError';
+  }
+}
+
+const SUPPORTED_FIELDS = new Set([
+  'date',
+  'subtitle',
+  'excerpt',
+  'category',
+  'tags',
+  'authors',
+  'author',
+  'layout',
+  'series',
+  'coverimage',
+  'sort',
+  'posts',
+  'featured',
+  'pinned',
+  'draft',
+  'latex',
+  'toc',
+  'commentable',
+  'redirectfrom',
+  'type',
+]);
+
+function normalizeLines(source: string): string[] {
+  return source.replace(/\r\n?/g, '\n').split('\n');
+}
+
+function isAdornmentLine(line: string): boolean {
+  const trimmed = line.trim();
+  return /^([=\-~^"`+#*])\1{2,}$/.test(trimmed);
+}
+
+function extractTitle(lines: string[]): { title: string; titleIndex: number; nextIndex: number } {
+  for (let i = 0; i + 1 < lines.length; i++) {
+    const titleLine = lines[i].trim();
+    const underline = lines[i + 1].trim();
+
+    if (!titleLine) continue;
+    if (/^\s/.test(lines[i])) continue;
+    if (!isAdornmentLine(underline)) continue;
+
+    return { title: titleLine, titleIndex: i, nextIndex: i + 2 };
+  }
+
+  throw new RstParseError('Missing top-level rST title.');
+}
+
+function parseBoolean(field: string, value: string): boolean {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  throw new RstParseError(`Invalid boolean for "${field}": ${value}`);
+}
+
+function parseCsv(value: string): string[] {
+  if (!value.trim()) return [];
+  return value
+    .split(',')
+    .map(part => part.trim())
+    .filter(Boolean);
+}
+
+function parseDate(value: string): string {
+  const match = value.match(/^(\d{4})-(\d{1,2})-(\d{1,2})$/);
+  if (!match) {
+    throw new RstParseError(`Invalid date: ${value}`);
+  }
+
+  const [, year, month, day] = match;
+  const normalized = `${year}-${month.padStart(2, '0')}-${day.padStart(2, '0')}`;
+
+  const parsed = new Date(`${normalized}T00:00:00Z`);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== normalized) {
+    throw new RstParseError(`Invalid date: ${value}`);
+  }
+
+  return normalized;
+}
+
+function parseSort(value: string): 'date-desc' | 'date-asc' | 'manual' {
+  if (value === 'date-desc' || value === 'date-asc' || value === 'manual') {
+    return value;
+  }
+  throw new RstParseError(`Invalid sort value: ${value}`);
+}
+
+function parseType(value: string): 'collection' {
+  if (value === 'collection') {
+    return value;
+  }
+  throw new RstParseError(`Invalid type value: ${value}`);
+}
+
+function setMetadataField(metadata: RstMetadata, field: string, value: string): void {
+  const key = field.toLowerCase();
+  if (!SUPPORTED_FIELDS.has(key)) return;
+
+  switch (key) {
+    case 'date':
+      metadata.date = parseDate(value);
+      break;
+    case 'subtitle':
+      metadata.subtitle = value;
+      break;
+    case 'excerpt':
+      metadata.excerpt = value;
+      break;
+    case 'category':
+      metadata.category = value;
+      break;
+    case 'tags':
+      metadata.tags = parseCsv(value);
+      break;
+    case 'authors':
+      metadata.authors = parseCsv(value);
+      break;
+    case 'author':
+      metadata.author = value;
+      break;
+    case 'layout':
+      metadata.layout = value;
+      break;
+    case 'series':
+      metadata.series = value;
+      break;
+    case 'coverimage':
+      metadata.coverImage = value;
+      break;
+    case 'sort':
+      metadata.sort = parseSort(value);
+      break;
+    case 'posts':
+      metadata.posts = parseCsv(value);
+      break;
+    case 'featured':
+      metadata.featured = parseBoolean(field, value);
+      break;
+    case 'pinned':
+      metadata.pinned = parseBoolean(field, value);
+      break;
+    case 'draft':
+      metadata.draft = parseBoolean(field, value);
+      break;
+    case 'latex':
+      metadata.latex = parseBoolean(field, value);
+      break;
+    case 'toc':
+      metadata.toc = parseBoolean(field, value);
+      break;
+    case 'commentable':
+      metadata.commentable = parseBoolean(field, value);
+      break;
+    case 'redirectfrom':
+      metadata.redirectFrom = parseCsv(value);
+      break;
+    case 'type':
+      metadata.type = parseType(value);
+      break;
+  }
+}
+
+function extractMetadata(lines: string[], startIndex: number): { metadata: RstMetadata; nextIndex: number } {
+  const metadata: RstMetadata = {};
+  let i = startIndex;
+  while (i < lines.length && !lines[i].trim()) i++;
+
+  while (i < lines.length) {
+    const match = lines[i].match(/^:([A-Za-z][\w-]*):\s*(.*)$/);
+    if (!match) break;
+
+    const field = match[1];
+    const continuation: string[] = [match[2]];
+    i++;
+
+    while (i < lines.length) {
+      const next = lines[i];
+      if (!next.trim()) break;
+      if (/^:([A-Za-z][\w-]*):\s*(.*)$/.test(next)) break;
+      if (/^\s+/.test(next)) {
+        continuation.push(next.trim());
+        i++;
+        continue;
+      }
+      break;
+    }
+
+    setMetadataField(metadata, field, continuation.join(' ').trim());
+
+    if (i < lines.length && !lines[i].trim()) {
+      i++;
+      if (i < lines.length && !/^:([A-Za-z][\w-]*):\s*(.*)$/.test(lines[i])) break;
+    }
+  }
+
+  while (i < lines.length && !lines[i].trim()) i++;
+  return { metadata, nextIndex: i };
+}
+
+function extractPreambleMetadata(lines: string[]): RstMetadata {
+  const metadata: RstMetadata = {};
+
+  for (let i = 0; i < lines.length; i++) {
+    const match = lines[i].match(/^:([A-Za-z][\w-]*):\s*(.*)$/);
+    if (!match) continue;
+
+    const field = match[1];
+    const continuation: string[] = [match[2]];
+    i++;
+
+    while (i < lines.length) {
+      const next = lines[i];
+      if (!next.trim()) break;
+      if (/^:([A-Za-z][\w-]*):\s*(.*)$/.test(next)) {
+        i--;
+        break;
+      }
+      if (/^\s+/.test(next)) {
+        continuation.push(next.trim());
+        i++;
+        continue;
+      }
+      i--;
+      break;
+    }
+
+    setMetadataField(metadata, field, continuation.join(' ').trim());
+  }
+
+  return metadata;
+}
+
+function mergeMetadata(base: RstMetadata, override: RstMetadata): RstMetadata {
+  return {
+    ...base,
+    ...override,
+    tags: override.tags ?? base.tags,
+    authors: override.authors ?? base.authors,
+    posts: override.posts ?? base.posts,
+    redirectFrom: override.redirectFrom ?? base.redirectFrom,
+  };
+}
+
+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)');
+}
+
+function detectHeadingLevel(adornment: string): number | null {
+  const marker = adornment.trim()[0];
+  if (marker === '=') return 2;
+  if (marker === '-' || marker === '~' || marker === '^') return 3;
+  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++;
+  if (i >= lines.length || !/^\s+/.test(lines[i])) {
+    return { content: [], nextIndex: startIndex };
+  }
+
+  const indent = lines[i].match(/^\s+/)?.[0].length ?? 0;
+  const content: string[] = [];
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (!line.trim()) {
+      content.push('');
+      i++;
+      continue;
+    }
+    const currentIndent = line.match(/^\s+/)?.[0].length ?? 0;
+    if (currentIndent < indent) break;
+    content.push(line.slice(indent));
+    i++;
+  }
+
+  while (content.length > 0 && content[0] === '') content.shift();
+  while (content.length > 0 && content[content.length - 1] === '') content.pop();
+
+  return { content, nextIndex: i };
+}
+
+export function rstToMarkdown(body: string): string {
+  const lines = normalizeLines(body);
+  const out: string[] = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    if (!trimmed) {
+      out.push('');
+      continue;
+    }
+
+    if (
+      i + 1 < lines.length &&
+      line.trim() &&
+      isAdornmentLine(lines[i + 1]) &&
+      !/^\s/.test(line)
+    ) {
+      const level = detectHeadingLevel(lines[i + 1]);
+      if (level !== null) {
+        out.push(`${'#'.repeat(level)} ${convertInlineRst(trimmed)}`);
+        out.push('');
+        i++;
+        continue;
+      }
+    }
+
+    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;
+      while (j < lines.length && !lines[j].trim()) j++;
+      while (j < lines.length && /^\s+:[A-Za-z-]+:/.test(lines[j])) {
+        const optionMatch = lines[j].match(/^\s+:([A-Za-z-]+):\s*(.*)$/);
+        if (optionMatch?.[1].toLowerCase() === 'alt') {
+          alt = optionMatch[2].trim();
+        }
+        j++;
+      }
+      out.push(`![${alt}](${imageMatch[1].trim()})`);
+      out.push('');
+      i = j - 1;
+      continue;
+    }
+
+    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 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('');
+      i = nextIndex - 1;
+      continue;
+    }
+
+    if (trimmed.endsWith('::') && !trimmed.startsWith('..')) {
+      const { content, nextIndex } = readIndentedBlock(lines, i + 1);
+      if (content.length > 0) {
+        const prefix = trimmed === '::' ? '' : convertInlineRst(trimmed.slice(0, -1));
+        if (prefix) {
+          out.push(prefix);
+          out.push('');
+        }
+        out.push('```');
+        out.push(...content);
+        out.push('```');
+        out.push('');
+        i = nextIndex - 1;
+        continue;
+      }
+    }
+
+    if (/^\s*[-*+]\s+/.test(line) || /^\s*\d+\.\s+/.test(line)) {
+      out.push(convertInlineRst(line));
+      continue;
+    }
+
+    out.push(convertInlineRst(line));
+  }
+
+  return out.join('\n').trim();
+}
+
+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, '')
+    .replace(/`[^`]*`/g, '')
+    .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 };
+}
+
+function calculateWordCount(content: string): number {
+  const { latinWords, hanChars } = countRstTokens(content);
+  return latinWords + hanChars;
+}
+
+function getHeadings(content: string): RstHeading[] {
+  const regex = /^(#{2,3})\s+(.*)$/gm;
+  const headings: RstHeading[] = [];
+  const slugger = new GithubSlugger();
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(content)) !== null) {
+    const level = match[1].length;
+    const text = match[2].trim();
+    headings.push({ id: slugger.slug(text), text, level });
+  }
+  return headings;
+}
+
+export function parseRstDocument(source: string): ParsedRstDocument {
+  const lines = normalizeLines(source);
+  const { title, titleIndex, nextIndex } = extractTitle(lines);
+  const preTitleMetadata = extractPreambleMetadata(lines.slice(0, titleIndex));
+  const { metadata: postTitleMetadata, nextIndex: contentIndex } = extractMetadata(lines, nextIndex);
+  const metadata = mergeMetadata(preTitleMetadata, postTitleMetadata);
+  const body = lines.slice(contentIndex).join('\n').trim();
+  const markdownBody = rstToMarkdown(body);
+
+  return {
+    title,
+    body,
+    markdownBody,
+    metadata,
+    headings: getHeadings(markdownBody),
+    excerpt: metadata.excerpt ?? '',
+    readingMinutes: calculateReadingMinutes(markdownBody),
+    wordCount: calculateWordCount(markdownBody),
+  };
+}

package/src/lib/series-redirects.ts

@@ -0,0 +1,42 @@
+import { getAllSeries, getSeriesData, PostData } from '@/lib/markdown';
+
+export function safeDecodeParam(param: string): string {
+  try {
+    return decodeURIComponent(param);
+  } catch {
+    return param;
+  }
+}
+
+function normalizeRedirectPath(path: string): string | null {
+  const trimmed = path.trim();
+  if (!trimmed) return null;
+
+  try {
+    const decoded = decodeURIComponent(trimmed);
+    return decoded.startsWith('/') ? decoded : `/${decoded}`;
+  } catch {
+    return null;
+  }
+}
+
+export function findSeriesByRedirectFrom(path: string): { slug: string; data: PostData } | null {
+  const normalizedPath = normalizeRedirectPath(path);
+  if (!normalizedPath) return null;
+
+  for (const seriesSlug of Object.keys(getAllSeries())) {
+    const data = getSeriesData(seriesSlug);
+    if (!data) continue;
+
+    const hasRedirect = (data.redirectFrom ?? []).some((redirectFrom) => {
+      const normalizedRedirect = normalizeRedirectPath(redirectFrom);
+      return normalizedRedirect === normalizedPath;
+    });
+
+    if (hasRedirect) {
+      return { slug: seriesSlug, data };
+    }
+  }
+
+  return null;
+}