dommief 0.1.0 → 0.1.2

package/src/config.ts

@@ -0,0 +1,258 @@
+import { z } from 'zod';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadConfigFromFile } from 'vite';
+import { DommiefError } from './markdown/errors.js';
+import type { ResolvedLocale, RouteConfig } from './types.js';
+import { createPluginHost } from './plugins.js';
+import type { DommiefPlugin } from './plugins.js';
+
+export type { ResolvedLocale } from './types.js';
+
+// Subset of CONFIG §1 needed by Phase 2 (DM-201). DM-901 extends it without restructuring.
+const LocaleInputSchema = z.object({
+  id: z.string().min(1).refine(
+    (s) => { try { Intl.getCanonicalLocales(s); return true; } catch { return false; } },
+    'phải là mã locale BCP 47 (vd "en-US", "vi-VN"; không dùng "_")',
+  ),
+  name: z.string().optional(),
+  base: z.string().startsWith('/', 'phải bắt đầu bằng "/"').optional(),
+  suffix: z.string().optional(),
+});
+
+export const ConfigSchema = z
+  .object({
+    title: z.string().default('Dommief'),
+    description: z.string().optional(),
+    base: z.string().startsWith('/', 'phải bắt đầu bằng "/" (URL tuyệt đối không được hỗ trợ)').default('/'),
+    outDir: z.string().default('dist'),
+    srcDir: z.string().default('docs'),
+    /** Khi `library`, tự động quét `src/` để hỗ trợ atom routing cho component library. */
+    preset: z.enum(['docs', 'library']).default('docs'),
+    docDirs: z.array(z.union([z.string(), z.object({ dir: z.string() })])).optional(),
+    forceKebabCase: z.boolean().default(true),
+    locales: z.array(LocaleInputSchema).default([{ id: 'en-US', name: 'English' }]),
+    themeConfig: z.record(z.string(), z.unknown()).default({}),
+    theme: z.string().default('dommief-theme-default'),
+    ssg: z
+      .object({
+        concurrency: z.number().int().positive().default(4),
+        /** Route không prerender nhưng VẪN phát shell (REVIEW §1 #17). Pattern: path chính xác hoặc `/prefix/*`. */
+        exclude: z.array(z.string()).default([]),
+        /** Route không phát file nào. */
+        noEmit: z.array(z.string()).default([]),
+      })
+      .default({ concurrency: 4, exclude: [], noEmit: [] }),
+    /** Cache transform md theo content-hash (DM-406). `--no-cache` tắt. */
+    cache: z.boolean().default(true),
+    /** Kiểm link nội bộ chết lúc build (DM-410). `--no-link-check` tắt. */
+    linkCheck: z.boolean().default(true),
+    dev: z.object({ port: z.number().int().positive().default(5173) }).default({ port: 5173 }),
+    /** sitemap.xml + robots.txt (DM-708, CONFIG §1.5). `false` (mặc định) = không phát; khai
+     * object thì `hostname` BẮT BUỘC (không đoán domain). */
+    sitemap: z
+      .union([z.literal(false), z.object({ hostname: z.string().url(), exclude: z.array(z.string()).default([]) })])
+      .default(false),
+    /** Ghi `robots.txt` trỏ tới sitemap. Mặc định: true nếu có sitemap, ngược lại false. */
+    robots: z.boolean().optional(),
+    /** Shiki lúc build + số dòng (CONFIG §1, DM-706). `shiki: false` = code thô. */
+    markdown: z
+      .object({
+        shiki: z.union([z.literal(false), z.object({ themes: z.object({ light: z.string(), dark: z.string() }) })]).default({ themes: { light: 'github-light', dark: 'github-dark' } }),
+        lineNumbers: z.boolean().default(false),
+      })
+      .default({ shiki: { themes: { light: 'github-light', dark: 'github-dark' } }, lineNumbers: false }),
+    /** Search index (DM-801). */
+    search: z.object({ enabled: z.boolean().default(true) }).default({ enabled: true }),
+    plugins: z.array(z.any()).default([]),
+  })
+  .strict();
+
+/** What the user writes in dommief.config.ts (input type: optional fields, locale union fields). */
+export type UserConfig = z.input<typeof ConfigSchema>;
+
+export interface ResolvedConfig extends RouteConfig {
+  /** Absolute cwd the config was resolved against. */
+  root: string;
+  title: string;
+  description?: string;
+  base: string;
+  outDir: string;
+  themeConfig: Record<string, unknown>;
+  theme: string;
+  ssg: { concurrency: number; exclude: string[]; noEmit: string[] };
+  cache: boolean;
+  linkCheck: boolean;
+  dev: { port: number };
+  sitemap: false | { hostname: string; exclude: string[] };
+  robots: boolean;
+  search: { enabled: boolean };
+  markdown: { shiki: false | { themes: { light: string; dark: string } }; lineNumbers: boolean };
+  plugins?: DommiefPlugin[];
+}
+
+export interface ResolveOptions {
+  cwd: string;
+  cli?: { base?: string | undefined; outDir?: string | undefined; cache?: boolean | undefined; linkCheck?: boolean | undefined };
+  env?: Record<string, string | undefined>;
+  /** Path of the loaded config file; only used to name the source in errors. */
+  configFile?: string | undefined;
+}
+
+export function defineConfig(config: UserConfig): UserConfig {
+  return config;
+}
+
+const CONFIG_FILES = ['dommief.config.ts', 'dommief.config.mts', 'dommief.config.js', 'dommief.config.mjs'];
+
+export async function loadConfigFile(opts: { cwd: string; configPath?: string }): Promise<{ path: string; config: UserConfig } | null> {
+  let file: string | undefined;
+  if (opts.configPath) {
+    file = path.resolve(opts.cwd, opts.configPath);
+    if (!fs.existsSync(file)) throw new DommiefError(`không tìm thấy file config: ${file}`, { code: 'config_not_found', file });
+  } else {
+    file = CONFIG_FILES.map((f) => path.join(opts.cwd, f)).find((p) => fs.existsSync(p));
+    if (!file) return null;
+  }
+  const loaded = await loadConfigFromFile({ command: 'serve', mode: 'development' }, file, opts.cwd, 'silent');
+  if (!loaded) return null;
+  return { path: loaded.path, config: loaded.config as UserConfig };
+}
+
+export function normalizeBase(base: string): string {
+  return base.endsWith('/') ? base : base + '/';
+}
+
+export function resolveConfig(userConfig: UserConfig, opts: ResolveOptions): ResolvedConfig {
+  const fileLabel = opts.configFile ? path.basename(opts.configFile) : 'dommief.config';
+  const sources: Record<string, string> = {};
+  for (const k of Object.keys(userConfig ?? {})) sources[k] = fileLabel;
+
+  // ponytail: shallow merge is exact while CLI/env only set top-level scalars (base, outDir).
+  // DM-901 adds sitemap.hostname / ssg.concurrency → switch to deep merge (objects deep, arrays replace).
+  let merged: Record<string, unknown> = { ...userConfig };
+  const layer = (key: string, value: string | undefined, source: string) => {
+    if (value === undefined || value === '') return;
+    merged[key] = value;
+    sources[key] = source;
+  };
+  // cac: `--no-cache` ⇒ cache === false. Chỉ `false` mới ghi đè; undefined/true giữ giá trị file.
+  if (opts.cli?.cache === false) { merged.cache = false; sources.cache = '--no-cache'; }
+  if (opts.cli?.linkCheck === false) { merged.linkCheck = false; sources.linkCheck = '--no-link-check'; }
+  layer('base', opts.cli?.base, '--base');
+  layer('outDir', opts.cli?.outDir, '--out-dir');
+  layer('base', opts.env?.DOMMIEF_BASE, 'DOMMIEF_BASE'); // env beats CLI (CONFIG §3.1) — on purpose
+  layer('outDir', opts.env?.DOMMIEF_OUT_DIR, 'DOMMIEF_OUT_DIR');
+
+  const fail = (keyPath: (string | number)[], message: string): never => {
+    const top = String(keyPath[0] ?? '');
+    const value = keyPath.reduce<unknown>((v, k) => (v as Record<string | number, unknown> | undefined)?.[k], merged);
+    const shown = value === undefined ? '(thiếu)' : JSON.stringify(value);
+    throw new DommiefError(
+      `cấu hình không hợp lệ\n  ${formatKeyPath(keyPath)}  ${shown}\n    ${message}\n    (nguồn: ${sources[top] ?? 'default'})`,
+      { code: 'config_invalid' },
+    );
+  };
+
+  const pluginHost = createPluginHost(Array.isArray(merged.plugins) ? merged.plugins : []);
+  const modified = pluginHost.applyModifyConfig(merged);
+  if (modified && typeof modified === 'object') merged = { ...merged, ...(modified as Record<string, unknown>) };
+
+  const parsed = ConfigSchema.safeParse(merged);
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0]!;
+    if (issue.code === 'unrecognized_keys') {
+      const key = issue.keys[0]!;
+      const hint = suggestKey(key);
+      fail([key], `key không được hỗ trợ${hint ? `; bạn muốn nói "${hint}"?` : ''}`);
+    }
+    fail(issue.path as (string | number)[], issue.message);
+  }
+  const c = parsed.data!;
+
+  const locales = resolveLocales(c.locales, fail);
+  const config: ResolvedConfig = {
+    root: opts.cwd,
+    title: c.title,
+    base: normalizeBase(c.base),
+    outDir: c.outDir,
+    srcDir: c.srcDir,
+    docDirs: (c.docDirs ?? [c.srcDir]).map((d) => (typeof d === 'string' ? { dir: d } : { dir: d.dir })),
+    forceKebabCase: c.forceKebabCase,
+    preset: c.preset,
+    locales,
+    themeConfig: c.themeConfig,
+    theme: c.theme,
+    ssg: c.ssg,
+    cache: c.cache,
+    linkCheck: c.linkCheck,
+    dev: c.dev,
+    sitemap: c.sitemap,
+    robots: c.robots ?? c.sitemap !== false,
+    search: c.search,
+    markdown: c.markdown,
+    plugins: (c.plugins ?? []) as DommiefPlugin[],
+  };
+  if (c.description !== undefined) config.description = c.description;
+  return config;
+}
+
+/** Load file at `root` + resolve with process env (and optional CLI flags). */
+export async function loadConfig(root: string, cli?: ResolveOptions['cli']): Promise<ResolvedConfig> {
+  const file = await loadConfigFile({ cwd: root });
+  return resolveConfig(file?.config ?? {}, { cwd: root, env: process.env, configFile: file?.path, ...(cli ? { cli } : {}) });
+}
+
+function resolveLocales(
+  input: z.output<typeof LocaleInputSchema>[],
+  fail: (keyPath: (string | number)[], message: string) => never,
+): ResolvedLocale[] {
+  // Mode is decided by locales[0] (CONFIG §1.2.1: base and suffix modes are mutually exclusive).
+  const suffixMode = input[0]?.suffix !== undefined;
+  const seen = new Set<string>();
+  return input.map((l, i) => {
+    if (seen.has(l.id)) fail(['locales', i, 'id'], `id "${l.id}" bị trùng`);
+    seen.add(l.id);
+    const name = l.name ?? l.id;
+    if (suffixMode) {
+      if (l.base !== undefined || l.suffix === undefined) {
+        fail(['locales', i], 'không trộn "base" và "suffix": locales[0] dùng chế độ suffix nên mọi locale phải khai "suffix" và không khai "base"');
+      }
+      return { id: l.id, name, base: '/', suffix: l.suffix! };
+    }
+    if (l.suffix !== undefined) {
+      fail(['locales', i], 'không trộn "base" và "suffix": locales[0] dùng chế độ base nên không locale nào được khai "suffix"');
+    }
+    const base = normalizeBase(l.base ?? (i === 0 ? '/' : `/${l.id}/`));
+    if (i > 0 && base === '/') {
+      fail(['locales', i, 'base'], `chỉ locale đầu tiên được dùng base "/". Đưa "${l.id}" lên đầu mảng hoặc đổi base.`);
+    }
+    return { id: l.id, name, base, suffix: '' };
+  });
+}
+
+function formatKeyPath(keyPath: (string | number)[]): string {
+  return keyPath.map((k, i) => (typeof k === 'number' ? `[${k}]` : i === 0 ? k : `.${k}`)).join('');
+}
+
+function suggestKey(key: string): string | undefined {
+  let best: string | undefined;
+  let bestDist = 3; // only suggest within edit distance ≤ 2
+  for (const known of Object.keys(ConfigSchema.shape)) {
+    const d = editDistance(key, known);
+    if (d < bestDist) [best, bestDist] = [known, d];
+  }
+  return best;
+}
+
+function editDistance(a: string, b: string): number {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const cur = [i];
+    for (let j = 1; j <= b.length; j++) {
+      cur[j] = Math.min(prev[j]! + 1, cur[j - 1]! + 1, prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = cur;
+  }
+  return prev[b.length]!;
+}

package/src/exclude.ts

@@ -0,0 +1,38 @@
+// Đặc tả: docs/backlog/DM-411.md. Khớp pattern trên ROUTE PATH (vd `/~demos/foo`), không phải
+// đường dẫn file trên đĩa. Chỉ cần `*` (một segment) và `**` (nhiều segment) nên tự chuyển glob
+// sang RegExp thay vì thêm dependency.
+
+const cache = new Map<string, RegExp>();
+
+/** `/~demos/*` -> /^\/~demos\/[^/]*$/ ; `**\/b` -> /^(?:.*\/)?b$/ */
+export function globToRegExp(pattern: string): RegExp {
+  let src = '';
+  for (let i = 0; i < pattern.length; i++) {
+    const c = pattern.charAt(i);
+    if (c === '*' && pattern.charAt(i + 1) === '*') {
+      const slash = pattern.charAt(i + 2) === '/';
+      src += slash ? '(?:.*/)?' : '.*';
+      i += slash ? 2 : 1;
+    } else if (c === '*') {
+      src += '[^/]*';
+    } else if (c === '?') {
+      src += '[^/]';
+    } else {
+      src += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${src}$`);
+}
+
+function matcher(pattern: string): RegExp {
+  const hit = cache.get(pattern);
+  if (hit) return hit;
+  const re = globToRegExp(pattern);
+  cache.set(pattern, re);
+  return re;
+}
+
+/** `matchExclude('/~demos/foo', ['/~demos/*']) === true`. Pattern rỗng -> không khớp gì. */
+export function matchExclude(path: string, patterns: string[]): boolean {
+  return patterns.some((p) => matcher(p).test(path));
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+export { defineConfig, loadConfig, loadConfigFile, resolveConfig } from './config.js';
+export type { ResolvedConfig, UserConfig } from './config.js';
+export { createPluginHost, registerPlugin, definePlugin, PluginHookHost, Hook } from './plugins.js';
+export type { DommiefPlugin, DommiefPluginObject, PluginSetup, BuildEndContext, PluginHookHost as PluginHooks } from './plugins.js';
+export { buildRouteTable } from './routes.js';
+export type { Route, RouteTable, RouteConfig, SiteData, ResolvedLocale } from './types.js';
+export { buildNav, buildSidebar, paginate, parseFrontmatter } from './siteFeatures.js';
+export type { FrontmatterMap, PaginationResult } from './siteFeatures.js';
+export { transformMarkdown } from './markdown/index.js';
+export { rehypeApi, buildApiTable, clearApiCache, hashFileContent } from './markdown/rehype-api.js';
+export type { ApiEntry, ApiProp } from './markdown/rehype-api.js';
+export { DommiefError, formatError } from './markdown/errors.js';
+export type { PageMeta, TocItem, TextFragment } from './markdown/index.js';
+export { createLogger } from './log.js';
+export type { Logger } from './log.js';
+export { buildSearchIndex, createMiniSearchConfig, INDEX_BUDGET_BYTES_PER_PAGE } from './search.js';
+export type { BuildSearchIndexOptions, BuildSearchIndexResult, MiniSearchConfig, SearchDocument } from './search.js';

package/src/link-check.ts

@@ -0,0 +1,101 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { TocItem } from './markdown/index.js';
+
+// Đặc tả: docs/backlog/DM-410.md. Neo vào HTML ĐÃ RENDER (không phải AST markdown): bắt được
+// cả href do theme/nav sinh, không chỉ link tác giả viết tay. Không fetch mạng (build tất định,
+// chạy offline được) — chỉ kiểm link nội bộ + asset.
+
+export interface LinkRef {
+  href: string;
+  routeId: string;
+  file: string;
+  /** `—` khi HTML không có `data-src-line` (href do raw HTML nhúng tay, không qua rehypeLink). */
+  line: string;
+}
+
+export type LinkIssueCode = 'link_target_missing' | 'link_anchor_missing' | 'link_asset_missing';
+export interface LinkIssue { code: LinkIssueCode; ref: LinkRef; }
+
+const HREF_RE = /<a\b[^>]*\shref="([^"]*)"[^>]*>/g;
+const ASSET_RE = /<(?:img|link)\b[^>]*\s(?:src|href)="([^"]*)"[^>]*>/g;
+const LINE_RE = /\sdata-src-line="(\d+)"/;
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i; // http:, mailto:, //cdn — không phải '/' (nội bộ) hay '#' (anchor)
+
+function extractRefs(re: RegExp, html: string, routeId: string, file: string): LinkRef[] {
+  const out: LinkRef[] = [];
+  let m: RegExpExecArray | null;
+  re.lastIndex = 0;
+  while ((m = re.exec(html))) {
+    const tag = m[0];
+    const href = m[1]!;
+    if (!href || href.startsWith('#') || EXTERNAL.test(href)) continue;
+    const line = tag.match(LINE_RE)?.[1] ?? '—';
+    out.push({ href, routeId, file, line });
+  }
+  return out;
+}
+
+/** Thu link `<a href>` nội bộ + asset `<img src>`/`<link href>` từ HTML đã render của một route. */
+export function collect(routeId: string, html: string, file: string): LinkRef[] {
+  return [...extractRefs(HREF_RE, html, routeId, file), ...extractRefs(ASSET_RE, html, routeId, file)];
+}
+
+
+
+export interface CheckOptions {
+  byPath: Record<string, { path: string }>;
+  /** routeId -> toc; thiếu nghĩa là route bị `ssg.exclude` (không prerender) — bỏ qua anchor check (§ ca h). */
+  tocByRoute: Record<string, TocItem[]>;
+  base: string;
+  /** `outDir` đã BUILD XONG (không phải `public/` nguồn): asset tĩnh được Vite copy thẳng,
+   * asset tương đối qua `rehypeImg` được Vite băm tên vào `assets/` — cả 2 chỉ tồn tại ở `outDir`. */
+  outDir: string;
+}
+
+/** `/sub/guide/intro` (base `/sub/`) -> `/guide/intro`. Bỏ base không idempotent: `/sub/sub/x` vẫn thiếu base lần 2 -> vẫn lỗi route, đúng ý DM-410 ca (e). */
+function stripBase(p: string, base: string): string {
+  const b = base.replace(/\/$/, '');
+  if (b && p.startsWith(b + '/')) return p.slice(b.length) || '/';
+  if (b && p === b) return '/';
+  return p;
+}
+
+export function check(refs: LinkRef[], opts: CheckOptions): LinkIssue[] {
+  const issues: LinkIssue[] = [];
+  for (const ref of refs) {
+    const isAsset = !!ref.href.match(/\.(png|jpe?g|gif|svg|webp|avif|ico|css|woff2?|ttf)(\?.*)?$/i);
+    const [rawPath, hash] = ref.href.split('#');
+    const cleanPath = (rawPath ?? '').split('?')[0]!;
+    if (isAsset) {
+      const relPath = stripBase(cleanPath, opts.base) || '/';
+      const onDisk = path.join(opts.outDir, decodeURIComponent(relPath));
+      if (!fs.existsSync(onDisk)) issues.push({ code: 'link_asset_missing', ref });
+      continue;
+    }
+    const routePath = stripBase(cleanPath, opts.base) || '/';
+    const target = opts.byPath[routePath];
+    if (!target) {
+      issues.push({ code: 'link_target_missing', ref });
+      continue;
+    }
+    if (hash) {
+      const toc = opts.tocByRoute[target.path] ?? opts.tocByRoute[routePath];
+      // route chưa prerender (ssg.exclude) -> không có toc -> không kiểm (không báo lỗi giả, ca h).
+      if (toc !== undefined && !toc.some((t) => t.id === hash)) {
+        issues.push({ code: 'link_anchor_missing', ref });
+      }
+    }
+  }
+  return issues;
+}
+
+const MAX_LINES = 20;
+
+/** Gom 1 lượt, tối đa 20 dòng; không log rải rác lúc kiểm (dễ đọc hơn khi có nhiều lỗi). */
+export function formatIssues(issues: LinkIssue[]): string {
+  const lines = issues.slice(0, MAX_LINES).map((i) => `${i.ref.file}:${i.ref.line}  ${i.ref.href}  (${i.code})`);
+  const rest = issues.length - lines.length;
+  if (rest > 0) lines.push(`… và ${rest} lỗi nữa`);
+  return lines.join('\n');
+}

package/src/log.ts

@@ -0,0 +1,10 @@
+export interface Logger { verbose: boolean; info(msg: string): void; debug(msg: string): void; warn(msg: string): void; error(msg: string): void; }
+export function createLogger(verbose = false): Logger {
+  return {
+    verbose,
+    info: (m) => console.log(m),
+    debug: (m) => { if (verbose) console.log('[debug]', m); },
+    warn: (m) => console.warn('[warn]', m),
+    error: (m) => console.error('[error]', m),
+  };
+}

package/src/markdown/errors.ts

@@ -0,0 +1,28 @@
+export class DommiefError extends Error {
+  file: string;
+  line?: number | undefined;
+  col?: number | undefined;
+  code?: string | undefined;
+  layout?: string | undefined;
+  constructor(message: string, opts: { file?: string; line?: number; col?: number; code?: string; layout?: string } = {}) {
+    super(message);
+    this.name = 'DommiefError';
+    this.file = opts.file ?? '';
+    this.line = opts.line;
+    this.col = opts.col;
+    this.code = opts.code;
+    this.layout = opts.layout;
+  }
+  format(): string {
+    const loc = this.line != null ? `:${this.line}${this.col != null ? ':' + this.col : ''}` : '';
+    const head = this.file ? `${this.file}${loc}` : loc.slice(1) || '';
+    return head ? `${head}: ${this.message}` : this.message;
+  }
+  toString() { return this.format(); }
+}
+
+export function formatError(err: unknown): string {
+  if (err instanceof DommiefError) return err.format();
+  if (err instanceof Error) return err.message;
+  return String(err);
+}

package/src/markdown/index.ts

@@ -0,0 +1,96 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkGfm from 'remark-gfm';
+import remarkDirective from 'remark-directive';
+import remarkRehype from 'remark-rehype';
+import rehypeRaw from 'rehype-raw';
+import { visit } from 'unist-util-visit';
+import type { Root as HastRoot } from 'hast';
+import { remarkMeta } from './remark-meta.js';
+import { rehypeSlug, rehypeAutolinkHeadings } from './rehype-slug.js';
+import { rehypeLink } from './rehype-link.js';
+import { rehypeImg } from './rehype-img.js';
+import { rehypeDesc, rehypeStrip } from './rehype-desc.js';
+import { rehypeText } from './rehype-text.js';
+import { rehypeDemo, remarkDemoMeta } from './rehype-demo.js';
+import { rehypeApi } from './rehype-api.js';
+import { remarkContainer } from './remark-container.js';
+import { remarkCodeMeta, rehypeCode, type RehypeCodeOptions } from './rehype-code.js';
+import { toModule } from './to-module.js';
+import { DommiefError } from './errors.js';
+import { createPluginHost, type PluginHookHost } from '../plugins.js';
+
+export interface TocItem { id: string; depth: number; title: string; }
+export interface TextFragment { type?: 'content' | 'title'; value: string; paraId?: number; tocIndex?: number; }
+export interface PageMeta {
+  frontmatter: Record<string, unknown>;
+  toc: TocItem[];
+  texts: TextFragment[];
+}
+
+export interface TransformMarkdownOptions {
+  remarkPlugins?: unknown[];
+  rehypePlugins?: unknown[];
+  hooks?: PluginHookHost;
+  plugins?: unknown[];
+  /** file md tuyệt đối → route; để `rehypeLink` đổi `./x.md` thành path route thật. */
+  byFile?: Record<string, { path: string }>;
+  /** `config.base` để gắn tiền tố cho link nội bộ. */
+  base?: string;
+  /** `config.markdown` (shiki + lineNumbers), DM-706. */
+  code?: RehypeCodeOptions;
+}
+export async function transformMarkdown(source: string, file: string, opts: TransformMarkdownOptions = {}): Promise<{ code: string; meta: PageMeta; warnings: string[]; apiSrcFiles: string[]; demos: { id: string; source: string }[] }> {
+  const host = opts.hooks ?? (opts.plugins ? createPluginHost(opts.plugins) : undefined);
+  const remarkPlugins = [...(opts.remarkPlugins ?? []), ...(host ? host.collectRemarkPlugins() : [])];
+  const rehypePlugins = [...(opts.rehypePlugins ?? []), ...(host ? host.collectRehypePlugins() : [])];
+  let processor: any;
+  try {
+    processor = unified()
+      .use(remarkParse)
+      .use(remarkFrontmatter, ['yaml'])
+      .use(remarkGfm)
+      .use(remarkDirective)
+      .use(remarkContainer)
+      .use(remarkMeta, { filename: file })
+      .use(remarkCodeMeta)
+      .use(remarkDemoMeta);
+    for (const p of remarkPlugins) processor = processor.use(p);
+    processor = processor
+      .use(remarkRehype, { allowDangerousHtml: true })
+      .use(rehypeRaw);
+    for (const p of rehypePlugins) processor = processor.use(p);
+    processor = processor
+      .use(rehypeSlug)
+      .use(rehypeAutolinkHeadings)
+      .use(rehypeLink, opts.byFile ? { byFile: opts.byFile, base: opts.base ?? '/' } : {})
+      .use(rehypeImg)
+      .use(rehypeDesc)
+      .use(rehypeStrip)
+      .use(rehypeText)
+      .use(rehypeDemo)
+      // sau rehypeDemo (fence `demo` đã thành DomDemo) và sau rehypeStrip/rehypeText (§3.16).
+      .use(rehypeCode, opts.code ?? {})
+      .use(rehypeApi);
+  } catch (e) {
+    throw new DommiefError('failed to build pipeline', { file });
+  }
+  const vfile: any = { data: {}, path: file };
+  let hast: HastRoot;
+  try {
+    const tree = processor.parse(source);
+    hast = await processor.run(tree, vfile) as HastRoot;
+  } catch (e) {
+    throw new DommiefError('markdown transform failed: ' + (e as Error).message, { file });
+  }
+  const apiSrcFiles = (vfile.data?.apiSrcFiles ?? []) as string[];
+  const meta: PageMeta = {
+    frontmatter: (vfile.data?.frontmatter ?? {}) as Record<string, unknown>,
+    toc: (vfile.data?.toc ?? []) as TocItem[],
+    texts: (vfile.data?.texts ?? []) as TextFragment[],
+  };
+  const demos = (vfile.data?.demos ?? []) as { id: string; source: string; src?: string }[];
+  const code = toModule(hast, meta, (vfile.data?.images ?? []) as { name: string; specifier: string }[], demos);
+  return { code, meta, warnings: (vfile.data?.warnings ?? []) as string[], apiSrcFiles, demos };
+}