@dsbasko/cookbook-engine 0.1.0

package/src/lib/lesson.ts

@@ -0,0 +1,66 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_LANG, type Lang } from './lang';
+import { resolveLecturesRoot } from './paths';
+
+export interface LessonContent {
+  markdown: string;
+  /**
+   * The language actually loaded. May differ from the requested lang when the
+   * requested translation is missing and the loader falls back (currently to
+   * Russian) — callers use this to decide whether to render a fallback banner.
+   */
+  lang: Lang;
+  /**
+   * True when the requested language was not available and the loader fell
+   * back to a different one. Always false when `lang === requested`.
+   */
+  fallbackUsed: boolean;
+}
+
+export interface GetLessonContentOptions {
+  lecturesRoot?: string;
+}
+
+export async function getLessonContent(
+  moduleId: string,
+  slug: string,
+  lang: Lang = DEFAULT_LANG,
+  options: GetLessonContentOptions = {},
+): Promise<LessonContent> {
+  const root = options.lecturesRoot ?? resolveLecturesRoot();
+  const primaryPath = getLessonReadmePath(moduleId, slug, lang, options);
+
+  try {
+    const markdown = await fs.readFile(primaryPath, 'utf8');
+    return { markdown, lang, fallbackUsed: false };
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== 'ENOENT') throw err;
+  }
+
+  if (lang !== 'ru') {
+    const fallbackPath = getLessonReadmePath(moduleId, slug, 'ru', { lecturesRoot: root });
+    try {
+      const markdown = await fs.readFile(fallbackPath, 'utf8');
+      return { markdown, lang: 'ru', fallbackUsed: true };
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (code !== 'ENOENT') throw err;
+    }
+  }
+
+  throw new Error(
+    `lesson README not found: ${moduleId}/${slug} (expected at ${primaryPath})`,
+  );
+}
+
+export function getLessonReadmePath(
+  moduleId: string,
+  slug: string,
+  lang: Lang = DEFAULT_LANG,
+  options: GetLessonContentOptions = {},
+): string {
+  const root = options.lecturesRoot ?? resolveLecturesRoot();
+  return path.join(root, moduleId, slug, 'i18n', lang, 'README.md');
+}

package/src/lib/markdown-components.tsx

@@ -0,0 +1,51 @@
+import type { ReactNode } from 'react';
+import { CodeBlock } from '@/components/CodeBlock';
+import { Callout, isCalloutType } from '@/components/Callout';
+import { DEFAULT_LANG, type Lang } from '@/lib/lang';
+
+type FigureProps = {
+  children?: ReactNode;
+} & Record<string, unknown>;
+
+export function makeMarkdownFigure(lang: Lang) {
+  return function MarkdownFigure(props: FigureProps) {
+    if (!('data-rehype-pretty-code-figure' in props)) {
+      const { children, ...rest } = props;
+      return <figure {...(rest as Record<string, string>)}>{children}</figure>;
+    }
+    const language = readLanguage(props);
+    return (
+      <CodeBlock language={language} lang={lang}>
+        {props.children}
+      </CodeBlock>
+    );
+  };
+}
+
+export const MarkdownFigure = makeMarkdownFigure(DEFAULT_LANG);
+
+type AsideProps = {
+  children?: ReactNode;
+} & Record<string, unknown>;
+
+export function makeMarkdownAside(lang: Lang) {
+  return function MarkdownAside(props: AsideProps) {
+    const calloutType = props['data-callout-type'];
+    if (isCalloutType(calloutType)) {
+      return (
+        <Callout type={calloutType} lang={lang}>
+          {props.children}
+        </Callout>
+      );
+    }
+    const { children, ...rest } = props;
+    return <aside {...(rest as Record<string, string>)}>{children}</aside>;
+  };
+}
+
+export const MarkdownAside = makeMarkdownAside(DEFAULT_LANG);
+
+function readLanguage(props: Record<string, unknown>): string {
+  const v = props['data-language'];
+  return typeof v === 'string' && v.length > 0 ? v : 'plaintext';
+}

package/src/lib/markdown.ts

@@ -0,0 +1,180 @@
+import { createElement, type ReactElement } from 'react';
+import { Fragment, jsx, jsxs } from 'react/jsx-runtime';
+import { unified, type Plugin } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkGfm from 'remark-gfm';
+import remarkRehype from 'remark-rehype';
+import rehypeSlug from 'rehype-slug';
+import rehypeAutolinkHeadings from 'rehype-autolink-headings';
+import rehypePrettyCode from 'rehype-pretty-code';
+import { toJsxRuntime } from 'hast-util-to-jsx-runtime';
+import type { Element, Root as HastRoot } from 'hast';
+import { remarkAlert } from 'remark-github-blockquote-alert';
+import remarkLessonImages from './mdx-plugins/remark-lesson-images';
+import remarkLinkRewrite from './mdx-plugins/remark-link-rewrite';
+import rehypeCallout from './mdx-plugins/rehype-callout';
+import type { Course } from './course';
+import { DEFAULT_LANG, type Lang } from './lang';
+import { LessonAwareLink } from '@/components/LessonAwareLink';
+import { makeMarkdownAside, makeMarkdownFigure } from './markdown-components';
+import { extractToc, type TocEntry } from './extract-toc';
+
+export interface RenderLessonMarkdownOptions {
+  moduleId: string;
+  slug: string;
+  basePath: string;
+  course: Course;
+  /**
+   * Active route language. Determines the `/<lang>/` prefix the rewriter
+   * stamps on emitted site URLs. Defaults to {@link DEFAULT_LANG}.
+   */
+  lang?: Lang;
+  /**
+   * Language of the README being rendered. When an EN route falls back to the
+   * RU README this differs from {@link lang}: the URL prefix stays `/en/` but
+   * relative sibling links inside the body anchor at `i18n/ru/`. Defaults to
+   * {@link lang}.
+   */
+  sourceLang?: Lang;
+}
+
+export interface RenderLessonMarkdownResult {
+  content: ReactElement;
+  toc: TocEntry[];
+}
+
+const PRETTY_CODE_OPTIONS = {
+  theme: { light: 'github-light', dark: 'night-owl' },
+  keepBackground: false,
+  defaultLang: 'plaintext',
+} as const;
+
+/**
+ * The lesson page already renders the `course.yaml` title as the page-level
+ * `<h1>` via `LessonLayout`. Lecture READMEs also start with their own `# Title`
+ * heading, which would produce a second `<h1>` in the article body — bad for
+ * the document outline, screen-reader navigation and SEO. Strip the leading
+ * `<h1>` from the lesson-content tree so the remaining `h2`/`h3` headings sit
+ * beneath the page H1 cleanly.
+ */
+const rehypeStripLeadingH1: Plugin<[], HastRoot> = () => {
+  return (tree) => {
+    for (let i = 0; i < tree.children.length; i += 1) {
+      const child = tree.children[i];
+      if (child.type !== 'element') continue;
+      if (child.tagName === 'h1') {
+        tree.children.splice(i, 1);
+      }
+      return;
+    }
+  };
+};
+
+/**
+ * rehype-pretty-code stamps `data-language` on the inner <pre>/<code>, but our
+ * CodeBlock wrapper renders at the <figure> level. Lift the language up so the
+ * figure component can show it without inspecting children.
+ */
+const rehypeLiftCodeBlockLanguage: Plugin<[], HastRoot> = () => {
+  return (tree) => {
+    walk(tree, (node) => {
+      if (node.tagName !== 'figure') return;
+      const props = node.properties;
+      if (!props || !('data-rehype-pretty-code-figure' in props)) return;
+      for (const child of node.children) {
+        if (child.type !== 'element' || child.tagName !== 'pre') continue;
+        const lang = (child.properties as Record<string, unknown> | undefined)?.['data-language'];
+        if (typeof lang === 'string') {
+          (props as Record<string, unknown>)['data-language'] = lang;
+        }
+        return;
+      }
+    });
+  };
+};
+
+function walk(node: HastRoot | Element, visit: (el: Element) => void) {
+  for (const child of node.children) {
+    if ((child as Element).type === 'element') {
+      visit(child as Element);
+      walk(child as Element, visit);
+    }
+  }
+}
+
+function hasAnchorDescendant(node: Element): boolean {
+  for (const child of node.children) {
+    if (child.type !== 'element') continue;
+    if (child.tagName === 'a') return true;
+    if (hasAnchorDescendant(child)) return true;
+  }
+  return false;
+}
+
+export async function renderLessonMarkdown(
+  source: string,
+  options: RenderLessonMarkdownOptions,
+): Promise<RenderLessonMarkdownResult> {
+  const processor = unified()
+    .use(remarkParse)
+    .use(remarkGfm)
+    .use(remarkAlert)
+    .use(remarkLessonImages, {
+      moduleId: options.moduleId,
+      slug: options.slug,
+      basePath: options.basePath,
+    })
+    .use(remarkLinkRewrite, {
+      moduleId: options.moduleId,
+      slug: options.slug,
+      basePath: options.basePath,
+      course: options.course,
+      lang: options.lang ?? DEFAULT_LANG,
+      sourceLang: options.sourceLang ?? options.lang ?? DEFAULT_LANG,
+    })
+    .use(remarkRehype, { allowDangerousHtml: false })
+    .use(rehypeStripLeadingH1)
+    .use(rehypeCallout)
+    .use(rehypeSlug)
+    .use(rehypeAutolinkHeadings, {
+      behavior: 'wrap',
+      properties: { className: ['heading-anchor'] },
+      // Skip headings that already contain an <a> (markdown links inside the
+      // heading text). Wrapping such a heading would emit invalid HTML
+      // (<a><h2>...<a>...</a>...</h2></a>) and trigger a hydration failure.
+      test: (node) => !hasAnchorDescendant(node),
+    })
+    .use(rehypePrettyCode, PRETTY_CODE_OPTIONS)
+    .use(rehypeLiftCodeBlockLanguage);
+
+  const mdast = processor.parse(source);
+  const hast = (await processor.run(mdast)) as HastRoot;
+
+  const toc = extractToc(hast);
+
+  // Wrap LessonAwareLink in a closure so it learns the build's basePath at
+  // render time without needing a React context (renderLessonMarkdown runs
+  // server-side; GateContext is client-only). The wrapper passes basePath
+  // down so the link can derive data-lesson-key from href on the server,
+  // which is what the inline gate-mark script needs to find at first paint.
+  const basePath = options.basePath;
+  const lang = options.lang ?? DEFAULT_LANG;
+  const LessonLink = (props: Record<string, unknown>) =>
+    createElement(LessonAwareLink, {
+      basePath,
+      ...(props as Record<string, unknown>),
+    } as never);
+
+  const content = toJsxRuntime(hast, {
+    Fragment,
+    jsx: jsx as never,
+    jsxs: jsxs as never,
+    components: {
+      a: LessonLink as never,
+      figure: makeMarkdownFigure(lang) as never,
+      aside: makeMarkdownAside(lang) as never,
+    },
+  }) as ReactElement;
+
+  return { content, toc };
+}

package/src/lib/mdx-plugins/rehype-callout.ts

@@ -0,0 +1,80 @@
+import type { Plugin } from 'unified';
+import type { Element, Root as HastRoot } from 'hast';
+
+export type CalloutType = 'note' | 'tip' | 'warning' | 'important' | 'caution';
+
+const CLASS_PREFIX = 'markdown-alert-';
+const TITLE_CLASS = 'markdown-alert-title';
+
+const CALLOUT_TYPES: ReadonlySet<CalloutType> = new Set([
+  'note',
+  'tip',
+  'warning',
+  'important',
+  'caution',
+]);
+
+/**
+ * Normalises GitHub-style alert markup produced by `remark-github-blockquote-alert`
+ * into our own React-friendly shape: `<aside data-callout-type="note">…</aside>`.
+ *
+ * The upstream plugin emits `<div class="markdown-alert markdown-alert-note">`
+ * with a leading title paragraph (`<p class="markdown-alert-title"><svg/>NOTE</p>`).
+ * We strip the auto-generated title and let the React `<Callout>` render its own
+ * header (with Russian label and icon), keeping the body content intact.
+ */
+const rehypeCallout: Plugin<[], HastRoot> = () => {
+  return (tree) => {
+    walk(tree, (node) => {
+      const type = readCalloutType(node);
+      if (!type) return;
+
+      node.tagName = 'aside';
+      const props = node.properties ?? {};
+      delete props.className;
+      (props as Record<string, unknown>)['data-callout-type'] = type;
+      node.properties = props;
+
+      node.children = node.children.filter((child) => {
+        if (child.type !== 'element') return true;
+        return !hasClass(child, TITLE_CLASS);
+      });
+    });
+  };
+};
+
+export default rehypeCallout;
+
+function readCalloutType(node: Element): CalloutType | null {
+  const classes = readClassList(node);
+  if (!classes.includes('markdown-alert')) return null;
+  for (const cls of classes) {
+    if (!cls.startsWith(CLASS_PREFIX)) continue;
+    const candidate = cls.slice(CLASS_PREFIX.length);
+    if (CALLOUT_TYPES.has(candidate as CalloutType)) {
+      return candidate as CalloutType;
+    }
+  }
+  return null;
+}
+
+function hasClass(node: Element, target: string): boolean {
+  return readClassList(node).includes(target);
+}
+
+function readClassList(node: Element): string[] {
+  const raw = node.properties?.className;
+  if (!raw) return [];
+  if (Array.isArray(raw)) return raw.filter((v): v is string => typeof v === 'string');
+  if (typeof raw === 'string') return raw.split(/\s+/).filter(Boolean);
+  return [];
+}
+
+function walk(node: HastRoot | Element, visit: (el: Element) => void) {
+  for (const child of node.children) {
+    if ((child as Element).type === 'element') {
+      visit(child as Element);
+      walk(child as Element, visit);
+    }
+  }
+}

package/src/lib/mdx-plugins/remark-lesson-images.ts

@@ -0,0 +1,109 @@
+export interface RemarkLessonImagesOptions {
+  moduleId: string;
+  slug: string;
+  basePath: string;
+}
+
+interface ImageLikeNode {
+  type: 'image' | 'definition';
+  url: string;
+  alt?: string | null;
+  identifier?: string;
+}
+
+interface ParentNode {
+  type: string;
+  children?: AstNode[];
+}
+
+type AstNode = ImageLikeNode | ParentNode;
+
+const PROTOCOL_RE = /^(?:[a-z][a-z0-9+.-]*:|\/\/|data:|mailto:|tel:|#)/i;
+
+const IMAGE_PREFIXES = ['./images/', '../../images/'] as const;
+
+function matchImagePrefix(url: string): string | null {
+  for (const prefix of IMAGE_PREFIXES) {
+    if (url.startsWith(prefix)) {
+      return prefix;
+    }
+  }
+  return null;
+}
+
+export function rewriteLessonImageUrl(
+  url: string,
+  options: RemarkLessonImagesOptions,
+  context: { nodeKind: 'image' | 'definition' },
+): string {
+  if (PROTOCOL_RE.test(url)) {
+    return url;
+  }
+
+  const prefix = matchImagePrefix(url);
+  if (prefix === null) {
+    throw new Error(
+      `remark-lesson-images: ${context.nodeKind} url "${url}" in ` +
+        `${options.moduleId}/${options.slug} is not allowed. ` +
+        `Only "./images/<file>" (legacy) or "../../images/<file>" (post-migration) ` +
+        `relative paths and absolute URLs (http(s)://, data:, mailto:, tel:) are supported.`,
+    );
+  }
+
+  const relative = url.slice(prefix.length);
+  if (relative.length === 0) {
+    throw new Error(
+      `remark-lesson-images: empty image filename in ${options.moduleId}/${options.slug}`,
+    );
+  }
+  if (relative.includes('..')) {
+    throw new Error(
+      `remark-lesson-images: image url "${url}" in ${options.moduleId}/${options.slug} ` +
+        `must not contain ".." segments after the images/ prefix`,
+    );
+  }
+
+  const basePath = options.basePath.replace(/\/+$/, '');
+  return `${basePath}/static/lectures/${options.moduleId}/${options.slug}/images/${relative}`;
+}
+
+export default function remarkLessonImages(options: RemarkLessonImagesOptions) {
+  if (!options || !options.moduleId || !options.slug) {
+    throw new Error(
+      'remark-lesson-images: options.moduleId and options.slug are required',
+    );
+  }
+
+  return function transformer(tree: AstNode): void {
+    walk(tree, (node) => {
+      if (node.type === 'image') {
+        const img = node as ImageLikeNode;
+        img.url = rewriteLessonImageUrl(img.url, options, {
+          nodeKind: 'image',
+        });
+        return;
+      }
+      // mdast `definition` nodes are shared between image and link references.
+      // Only claim ones that clearly point to a lesson image; let
+      // remark-link-rewrite handle the rest.
+      if (node.type === 'definition') {
+        const def = node as ImageLikeNode;
+        if (typeof def.url === 'string' && matchImagePrefix(def.url) !== null) {
+          def.url = rewriteLessonImageUrl(def.url, options, {
+            nodeKind: 'definition',
+          });
+        }
+      }
+    });
+  };
+}
+
+function walk(node: AstNode, visitor: (node: AstNode) => void): void {
+  visitor(node);
+  const children = (node as ParentNode).children;
+  if (Array.isArray(children)) {
+    for (const child of children) {
+      walk(child, visitor);
+    }
+  }
+}