duckfn-docs-kit 0.4.1 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "duckfn-docs-kit",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Shared Docusaurus building blocks (TOC toggle, home-page web components, brand tokens, remark version placeholder) for duckfn-family extension docs sites.",
   "license": "MIT",
   "keywords": [

package/src/sql/collect.ts

@@ -1,136 +1,136 @@
-/**
- * Node-side collector for runnable SQL blocks: walks a docs site's content and
- * returns every fenced block whose info string is a runnable config.
- *
- * The metastring contract belongs to `sql/remark.ts` (one parser, exported as
- * `parseRunnableSqlMeta`), so the blocks collected here are exactly the ones
- * the build turns into `<dfk-sql>` — a CI check over this list therefore covers
- * what the site actually publishes.
- *
- * Fences follow CommonMark closely enough for a docs tree: a closing fence has
- * to use the same character, be at least as long, and carry no info string.
- * That is what keeps a ```sql example *inside* a ````md wrapper (as
- * `docs-kit/runnable-sql.md` shows the metastring) from being collected as a
- * block of its own.
- */
-import {readFileSync, readdirSync, statSync} from 'node:fs';
-import {join, relative, sep} from 'node:path';
-
-import {parseRunnableSqlMeta, type RunnableSqlConfig} from './remark';
-
-/** One runnable block, positioned so a failure can name it. */
-export interface RunnableSqlBlock {
-  /** Path relative to the site root, always with forward slashes. */
-  file: string;
-  /** 1-based line of the opening fence. */
-  line: number;
-  config: RunnableSqlConfig;
-  sql: string;
-}
-
-export interface CollectRunnableSqlOptions {
-  /** Site root the reported paths are relative to, and the base of a relative dir. */
-  siteDir: string;
-  /**
-   * Directories to scan (absolute, or relative to `siteDir`). Missing ones are
-   * skipped rather than reported: a site may have no translations.
-   */
-  contentDirs: readonly string[];
-  /** File extensions to scan; both `.md` and `.mdx` are markdown to us. */
-  extensions?: readonly string[];
-}
-
-const DEFAULT_EXTENSIONS = ['.md', '.mdx'] as const;
-
-/** Every runnable block under `contentDirs`, in file order, then line order. */
-export function collectRunnableSql(options: CollectRunnableSqlOptions): RunnableSqlBlock[] {
-  const {siteDir, contentDirs, extensions = DEFAULT_EXTENSIONS} = options;
-  const files: string[] = [];
-  for (const dir of contentDirs) {
-    collectFiles(join(siteDir, dir), extensions, files);
-  }
-  const blocks: RunnableSqlBlock[] = [];
-  for (const file of files.sort()) {
-    for (const block of blocksOf(readFileSync(file, 'utf8'))) {
-      blocks.push({
-        ...block,
-        file: relative(siteDir, file).split(sep).join('/'),
-      });
-    }
-  }
-  return blocks;
-}
-
-function collectFiles(dir: string, extensions: readonly string[], out: string[]): void {
-  let entries: string[];
-  try {
-    entries = readdirSync(dir);
-  } catch {
-    // Nothing to scan here (typically a translation that does not exist yet).
-    return;
-  }
-  for (const name of entries) {
-    const path = join(dir, name);
-    if (statSync(path).isDirectory()) {
-      collectFiles(path, extensions, out);
-    } else if (extensions.some((extension) => name.endsWith(extension))) {
-      out.push(path);
-    }
-  }
-}
-
-interface RawBlock {
-  line: number;
-  config: RunnableSqlConfig;
-  sql: string;
-}
-
-/** The runnable blocks of one markdown document. */
-function blocksOf(text: string): RawBlock[] {
-  const lines = text.split('\n');
-  const out: RawBlock[] = [];
-  let open: {marker: string; info: string; line: number} | null = null;
-  let body: string[] = [];
-
-  for (let index = 0; index < lines.length; index++) {
-    const line = lines[index] ?? '';
-    const fence = /^(`{3,}|~{3,})(.*)$/.exec(line);
-    if (!fence) {
-      if (open) {
-        body.push(line);
-      }
-      continue;
-    }
-    const [marker, info] = [fence[1] ?? '', (fence[2] ?? '').trim()];
-    if (!open) {
-      open = {marker, info, line: index + 1};
-      body = [];
-      continue;
-    }
-    const closes =
-      marker.charAt(0) === open.marker.charAt(0) && marker.length >= open.marker.length && info === '';
-    if (!closes) {
-      // A shorter or differently marked fence is content of the open block.
-      body.push(line);
-      continue;
-    }
-    if (open.info.startsWith('sql')) {
-      const config = parseRunnableSqlMeta(open.info.slice('sql'.length).trim());
-      if (config) {
-        out.push({line: open.line, config, sql: body.join('\n')});
-      }
-    }
-    open = null;
-    body = [];
-  }
-  return out;
-}
-
-/**
- * Whether a block is expected to fail — the block's own `"expect": "error"`
- * metadata, never its prose or its comments: an expectation that the SQL test
- * suite acts on has to be data, not a string match on a comment.
- */
-export function expectsError(config: RunnableSqlConfig): boolean {
-  return config.expect === 'error';
-}
+/**
+ * Node-side collector for runnable SQL blocks: walks a docs site's content and
+ * returns every fenced block whose info string is a runnable config.
+ *
+ * The metastring contract belongs to `sql/remark.ts` (one parser, exported as
+ * `parseRunnableSqlMeta`), so the blocks collected here are exactly the ones
+ * the build turns into `<dfk-sql>` — a CI check over this list therefore covers
+ * what the site actually publishes.
+ *
+ * Fences follow CommonMark closely enough for a docs tree: a closing fence has
+ * to use the same character, be at least as long, and carry no info string.
+ * That is what keeps a ```sql example *inside* a ````md wrapper (as
+ * `docs-kit/runnable-sql.md` shows the metastring) from being collected as a
+ * block of its own.
+ */
+import {readFileSync, readdirSync, statSync} from 'node:fs';
+import {join, relative, sep} from 'node:path';
+
+import {parseRunnableSqlMeta, type RunnableSqlConfig} from './remark';
+
+/** One runnable block, positioned so a failure can name it. */
+export interface RunnableSqlBlock {
+  /** Path relative to the site root, always with forward slashes. */
+  file: string;
+  /** 1-based line of the opening fence. */
+  line: number;
+  config: RunnableSqlConfig;
+  sql: string;
+}
+
+export interface CollectRunnableSqlOptions {
+  /** Site root the reported paths are relative to, and the base of a relative dir. */
+  siteDir: string;
+  /**
+   * Directories to scan (absolute, or relative to `siteDir`). Missing ones are
+   * skipped rather than reported: a site may have no translations.
+   */
+  contentDirs: readonly string[];
+  /** File extensions to scan; both `.md` and `.mdx` are markdown to us. */
+  extensions?: readonly string[];
+}
+
+const DEFAULT_EXTENSIONS = ['.md', '.mdx'] as const;
+
+/** Every runnable block under `contentDirs`, in file order, then line order. */
+export function collectRunnableSql(options: CollectRunnableSqlOptions): RunnableSqlBlock[] {
+  const {siteDir, contentDirs, extensions = DEFAULT_EXTENSIONS} = options;
+  const files: string[] = [];
+  for (const dir of contentDirs) {
+    collectFiles(join(siteDir, dir), extensions, files);
+  }
+  const blocks: RunnableSqlBlock[] = [];
+  for (const file of files.sort()) {
+    for (const block of blocksOf(readFileSync(file, 'utf8'))) {
+      blocks.push({
+        ...block,
+        file: relative(siteDir, file).split(sep).join('/'),
+      });
+    }
+  }
+  return blocks;
+}
+
+function collectFiles(dir: string, extensions: readonly string[], out: string[]): void {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    // Nothing to scan here (typically a translation that does not exist yet).
+    return;
+  }
+  for (const name of entries) {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) {
+      collectFiles(path, extensions, out);
+    } else if (extensions.some((extension) => name.endsWith(extension))) {
+      out.push(path);
+    }
+  }
+}
+
+interface RawBlock {
+  line: number;
+  config: RunnableSqlConfig;
+  sql: string;
+}
+
+/** The runnable blocks of one markdown document. */
+function blocksOf(text: string): RawBlock[] {
+  const lines = text.split('\n');
+  const out: RawBlock[] = [];
+  let open: {marker: string; info: string; line: number} | null = null;
+  let body: string[] = [];
+
+  for (let index = 0; index < lines.length; index++) {
+    const line = lines[index] ?? '';
+    const fence = /^(`{3,}|~{3,})(.*)$/.exec(line);
+    if (!fence) {
+      if (open) {
+        body.push(line);
+      }
+      continue;
+    }
+    const [marker, info] = [fence[1] ?? '', (fence[2] ?? '').trim()];
+    if (!open) {
+      open = {marker, info, line: index + 1};
+      body = [];
+      continue;
+    }
+    const closes =
+      marker.charAt(0) === open.marker.charAt(0) && marker.length >= open.marker.length && info === '';
+    if (!closes) {
+      // A shorter or differently marked fence is content of the open block.
+      body.push(line);
+      continue;
+    }
+    if (open.info.startsWith('sql')) {
+      const config = parseRunnableSqlMeta(open.info.slice('sql'.length).trim());
+      if (config) {
+        out.push({line: open.line, config, sql: body.join('\n')});
+      }
+    }
+    open = null;
+    body = [];
+  }
+  return out;
+}
+
+/**
+ * Whether a block is expected to fail — the block's own `"expect": "error"`
+ * metadata, never its prose or its comments: an expectation that the SQL test
+ * suite acts on has to be data, not a string match on a comment.
+ */
+export function expectsError(config: RunnableSqlConfig): boolean {
+  return config.expect === 'error';
+}

package/src/sql/verify.ts

@@ -1,339 +1,339 @@
-/**
- * `duckfn-docs-kit/sql/verify` — runs every runnable SQL block a docs site
- * publishes, so a broken example is caught by CI instead of by a reader
- * clicking **Run**.
- *
- * It is the same environment the site gives a block: DuckDB-Wasm in a browser,
- * the site's extension preloaded, one instance per page and the page's blocks
- * sharing a connection (see `sql/browserRunner.ts` for why this is a real
- * browser and not the Node worker the kit used to run).
- *
- * A block may fail *on purpose* — half the guide ends on a statement that
- * demonstrates an error. Such a block says so in its own metadata
- * (`{"type":"duckfn","expect":"error"}`) and is then **required** to fail: one
- * that starts succeeding is reported too, because an expectation the suite acts
- * on has to be data rather than a string match on a comment. Only blocks that
- * did not behave as declared make the command exit non-zero.
- */
-import {readdirSync, statSync, writeFileSync} from 'node:fs';
-import {join, resolve} from 'node:path';
-
-import {collectRunnableSql, expectsError, type RunnableSqlBlock} from './collect';
-import {BrowserSqlRunner, type WasmPlatform} from './browserRunner';
-
-export interface VerifyOptions {
-  /** Docs site root; defaults to the working directory. */
-  siteDir?: string;
-  /** Content directories relative to the site root; defaults to the site layout. */
-  contentDirs?: readonly string[];
-  /**
-   * The extension to `LOAD`: a path, or an absolute `http(s)` URL. Defaults to
-   * the single file under `<siteDir>/static/duckdb-extensions/`.
-   */
-  extension?: string;
-  /** DuckDB-Wasm platform, which must match the extension build. */
-  platform?: WasmPlatform;
-  /** Engine wasm override, for pinning a specific DuckDB-Wasm build. */
-  engine?: string;
-  /** Per-block timeout in milliseconds; a hang is reported instead of blocking CI. */
-  timeoutMs?: number;
-  /**
-   * The browser executable that runs the blocks. Defaults to a detected
-   * Chrome/Edge; the `DFK_BROWSER` environment variable is the same override.
-   */
-  browser?: string;
-  /** Write the full result list here as JSON. */
-  reportFile?: string;
-}
-
-/** What happened to a block, judged against what it declared. */
-export type BlockOutcome =
-  /** Ran, and was expected to run. */
-  | 'ok'
-  /** Failed, and declared `"expect": "error"`. */
-  | 'error-as-expected'
-  /** Failed, but was expected to run. */
-  | 'unexpected-error'
-  /** Ran, but declared `"expect": "error"`. */
-  | 'unexpected-success';
-
-export interface BlockResult {
-  file: string;
-  line: number;
-  outcome: BlockOutcome;
-  detail: string;
-}
-
-export interface VerifyReport {
-  blocks: BlockResult[];
-  /** Blocks that behaved as declared: they ran, or they failed as declared. */
-  asDeclared: BlockResult[];
-  /** Blocks that did not behave as declared — the ones that should fail CI. */
-  unexpected: BlockResult[];
-}
-
-const DEFAULT_CONTENT = ['docs', 'i18n'] as const;
-const DEFAULT_TIMEOUT_MS = 30_000;
-
-/** Runs every runnable block of the site and returns the outcome of each. */
-export async function verifySqlDocs(options: VerifyOptions = {}): Promise<VerifyReport> {
-  const siteDir = resolve(options.siteDir ?? process.cwd());
-  const blocks = collectRunnableSql({
-    siteDir,
-    contentDirs: options.contentDirs ?? defaultContentDirs(siteDir),
-  });
-  const requested = options.extension;
-  const extension = requested
-    ? /^https?:\/\//i.test(requested)
-      ? requested
-      : resolve(requested)
-    : defaultExtension(siteDir);
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-
-  // No working directory: in a browser DuckDB's file system is the instance's
-  // own memory, so `COPY … TO` / `dfn_file_write_*` never touch the docs tree —
-  // they land in the page and vanish on the next `newPage()`.
-  const results = await runPages(blocks, extension, options, timeoutMs);
-
-  const report: VerifyReport = {
-    blocks: results,
-    asDeclared: results.filter((result) => result.outcome === 'ok' || result.outcome === 'error-as-expected'),
-    unexpected: results.filter(
-      (result) => result.outcome === 'unexpected-error' || result.outcome === 'unexpected-success',
-    ),
-  };
-  if (options.reportFile) {
-    writeFileSync(options.reportFile, `${JSON.stringify(report, null, 2)}\n`);
-  }
-  return report;
-}
-
-/** Opens one page per content file and runs that file's blocks against it. */
-async function runPages(
-  blocks: readonly RunnableSqlBlock[],
-  extension: string,
-  options: VerifyOptions,
-  timeoutMs: number,
-): Promise<BlockResult[]> {
-  const runner = await BrowserSqlRunner.create({
-    extension,
-    platform: options.platform,
-    engine: options.engine,
-    browser: options.browser,
-  });
-  const results: BlockResult[] = [];
-  try {
-    let currentFile: string | null = null;
-    for (const block of blocks) {
-      if (block.file !== currentFile) {
-        currentFile = block.file;
-        await runner.newPage();
-      }
-      results.push(await runBlock(runner, block, timeoutMs));
-    }
-  } finally {
-    await runner.close();
-  }
-  return results;
-}
-
-/** Runs one block and judges the result against the block's own declaration. */
-async function runBlock(
-  runner: BrowserSqlRunner,
-  block: RunnableSqlBlock,
-  timeoutMs: number,
-): Promise<BlockResult> {
-  const declaredError = expectsError(block.config);
-  try {
-    const result = await withTimeout(runner.run(block.sql), timeoutMs);
-    return {
-      file: block.file,
-      line: block.line,
-      outcome: declaredError ? 'unexpected-success' : 'ok',
-      detail: declaredError
-        ? `declared "expect": "error" but succeeded (${result.rows}×${result.columns})`
-        : `ok (${result.rows}×${result.columns})`,
-    };
-  } catch (error) {
-    const message = String((error as Error)?.message ?? error).split('\n')[0] ?? '';
-    return {
-      file: block.file,
-      line: block.line,
-      outcome: declaredError ? 'error-as-expected' : 'unexpected-error',
-      detail: message,
-    };
-  }
-}
-
-function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
-  let timer: NodeJS.Timeout | undefined;
-  const timeout = new Promise<never>((_resolve, reject) => {
-    timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
-  });
-  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
-}
-
-/**
- * Where a Docusaurus site keeps its pages: the English sources in `docs/`, and
- * each translation under `i18n/<locale>/docusaurus-plugin-content-docs/current/`.
- */
-function defaultContentDirs(siteDir: string): string[] {
-  const dirs: string[] = [];
-  if (isDirectory(join(siteDir, DEFAULT_CONTENT[0]))) {
-    dirs.push(DEFAULT_CONTENT[0]);
-  }
-  const i18n = join(siteDir, DEFAULT_CONTENT[1]);
-  if (isDirectory(i18n)) {
-    for (const locale of readdirSync(i18n)) {
-      const translated = join(i18n, locale, 'docusaurus-plugin-content-docs', 'current');
-      if (isDirectory(translated)) {
-        dirs.push(join('i18n', locale, 'docusaurus-plugin-content-docs', 'current'));
-      }
-    }
-  }
-  return dirs.length > 0 ? dirs : ['.'];
-}
-
-/** The site's preloaded extension, as `dfkExtensions` places it under `static/`. */
-function defaultExtension(siteDir: string): string {
-  const dir = join(siteDir, 'static', 'duckdb-extensions');
-  const candidates = isDirectory(dir)
-    ? readdirSync(dir).filter((name) => name.endsWith('.duckdb_extension.wasm'))
-    : [];
-  if (candidates.length === 0) {
-    throw new Error(
-      `sql/verify: no extension found in ${dir} — pass --extension <file|url>, or let the site's ` +
-        `extension preload plugin fetch it first`,
-    );
-  }
-  if (candidates.length > 1) {
-    throw new Error(
-      `sql/verify: several extensions found in ${dir} (${candidates.join(', ')}) — ` +
-        `pass --extension to pick one`,
-    );
-  }
-  return join(dir, candidates[0] as string);
-}
-
-function isDirectory(path: string): boolean {
-  return statSync(path, {throwIfNoEntry: false})?.isDirectory() ?? false;
-}
-
-export interface CliOptions extends VerifyOptions {
-  quiet?: boolean;
-}
-
-/**
- * `duckfn-sql-verify` — the command line around {@link verifySqlDocs}.
- *
- * Exit code 1 when a block did not behave as it declared, so a docs site can
- * wire it straight into `npm test`.
- */
-export async function cliMain(argv: readonly string[]): Promise<void> {
-  const options = parseArgs(argv);
-  if (options.help) {
-    process.stdout.write(USAGE);
-    return;
-  }
-  const started = Date.now();
-  const report = await verifySqlDocs(options);
-  const seconds = ((Date.now() - started) / 1000).toFixed(1);
-  const declaredFailures = report.blocks.filter(
-    (result) => result.outcome === 'error-as-expected',
-  ).length;
-  if (!options.quiet) {
-    process.stdout.write(`\n${report.blocks.length} block(s) in ${seconds}s\n`);
-    process.stdout.write(
-      `  ${report.asDeclared.length} as declared (${declaredFailures} erroring on purpose), ` +
-        `${report.unexpected.length} unexpected\n`,
-    );
-  }
-  if (report.unexpected.length > 0) {
-    process.stdout.write('unexpected behaviour:\n');
-    for (const block of report.unexpected) {
-      process.stdout.write(`- ${block.file}:${block.line} [${block.outcome}] :: ${block.detail}\n`);
-    }
-    process.exitCode = 1;
-  }
-}
-
-const USAGE = `Usage: duckfn-sql-verify [options]
-
-Runs every runnable SQL block of a duckfn docs site in a headless browser
-(DuckDB-Wasm), and checks that each one behaves as its own metadata declares
-("expect": "error" for a block that demonstrates a failure).
-
-  --site <dir>          Docs site root (default: the working directory)
-  --content <dir>       Content directory, relative to the site root (repeatable;
-                        default: docs/ plus every i18n/<locale>/… translation)
-  --extension <path>    The extension to preload: a .duckdb_extension.wasm path,
-                        or an absolute http(s) URL (default: the single file under
-                        static/duckdb-extensions/)
-  --platform <eh|mvp>   DuckDB-Wasm bundle, which must match the extension build
-                        (default: eh)
-  --engine <path>       Engine wasm override
-  --browser <path>      Browser executable (default: a detected Chrome/Edge,
-                        or the DFK_BROWSER environment variable)
-  --timeout <ms>        Per-block timeout (default: 30000)
-  --report <file>       Write the full result list as JSON
-  --quiet               Only report unexpected behaviour
-  --help                Show this help
-`;
-
-interface ParsedArgs extends CliOptions {
-  help?: boolean;
-}
-
-function parseArgs(argv: readonly string[]): ParsedArgs {
-  const options: ParsedArgs = {};
-  const content: string[] = [];
-  for (let index = 0; index < argv.length; index++) {
-    const arg = argv[index];
-    const next = (): string => {
-      const value = argv[++index];
-      if (value === undefined) {
-        throw new Error(`sql/verify: ${arg} needs a value`);
-      }
-      return value;
-    };
-    switch (arg) {
-      case '--site':
-        options.siteDir = next();
-        break;
-      case '--content':
-        content.push(next());
-        break;
-      case '--extension':
-        options.extension = next();
-        break;
-      case '--platform':
-        options.platform = next() as WasmPlatform;
-        break;
-      case '--engine':
-        options.engine = next();
-        break;
-      case '--browser':
-        options.browser = next();
-        break;
-      case '--timeout':
-        options.timeoutMs = Number(next());
-        break;
-      case '--report':
-        options.reportFile = next();
-        break;
-      case '--quiet':
-        options.quiet = true;
-        break;
-      case '--help':
-      case '-h':
-        options.help = true;
-        break;
-      default:
-        throw new Error(`sql/verify: unknown option ${arg}`);
-    }
-  }
-  if (content.length > 0) {
-    options.contentDirs = content;
-  }
-  return options;
-}
+/**
+ * `duckfn-docs-kit/sql/verify` — runs every runnable SQL block a docs site
+ * publishes, so a broken example is caught by CI instead of by a reader
+ * clicking **Run**.
+ *
+ * It is the same environment the site gives a block: DuckDB-Wasm in a browser,
+ * the site's extension preloaded, one instance per page and the page's blocks
+ * sharing a connection (see `sql/browserRunner.ts` for why this is a real
+ * browser and not the Node worker the kit used to run).
+ *
+ * A block may fail *on purpose* — half the guide ends on a statement that
+ * demonstrates an error. Such a block says so in its own metadata
+ * (`{"type":"duckfn","expect":"error"}`) and is then **required** to fail: one
+ * that starts succeeding is reported too, because an expectation the suite acts
+ * on has to be data rather than a string match on a comment. Only blocks that
+ * did not behave as declared make the command exit non-zero.
+ */
+import {readdirSync, statSync, writeFileSync} from 'node:fs';
+import {join, resolve} from 'node:path';
+
+import {collectRunnableSql, expectsError, type RunnableSqlBlock} from './collect';
+import {BrowserSqlRunner, type WasmPlatform} from './browserRunner';
+
+export interface VerifyOptions {
+  /** Docs site root; defaults to the working directory. */
+  siteDir?: string;
+  /** Content directories relative to the site root; defaults to the site layout. */
+  contentDirs?: readonly string[];
+  /**
+   * The extension to `LOAD`: a path, or an absolute `http(s)` URL. Defaults to
+   * the single file under `<siteDir>/static/duckdb-extensions/`.
+   */
+  extension?: string;
+  /** DuckDB-Wasm platform, which must match the extension build. */
+  platform?: WasmPlatform;
+  /** Engine wasm override, for pinning a specific DuckDB-Wasm build. */
+  engine?: string;
+  /** Per-block timeout in milliseconds; a hang is reported instead of blocking CI. */
+  timeoutMs?: number;
+  /**
+   * The browser executable that runs the blocks. Defaults to a detected
+   * Chrome/Edge; the `DFK_BROWSER` environment variable is the same override.
+   */
+  browser?: string;
+  /** Write the full result list here as JSON. */
+  reportFile?: string;
+}
+
+/** What happened to a block, judged against what it declared. */
+export type BlockOutcome =
+  /** Ran, and was expected to run. */
+  | 'ok'
+  /** Failed, and declared `"expect": "error"`. */
+  | 'error-as-expected'
+  /** Failed, but was expected to run. */
+  | 'unexpected-error'
+  /** Ran, but declared `"expect": "error"`. */
+  | 'unexpected-success';
+
+export interface BlockResult {
+  file: string;
+  line: number;
+  outcome: BlockOutcome;
+  detail: string;
+}
+
+export interface VerifyReport {
+  blocks: BlockResult[];
+  /** Blocks that behaved as declared: they ran, or they failed as declared. */
+  asDeclared: BlockResult[];
+  /** Blocks that did not behave as declared — the ones that should fail CI. */
+  unexpected: BlockResult[];
+}
+
+const DEFAULT_CONTENT = ['docs', 'i18n'] as const;
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** Runs every runnable block of the site and returns the outcome of each. */
+export async function verifySqlDocs(options: VerifyOptions = {}): Promise<VerifyReport> {
+  const siteDir = resolve(options.siteDir ?? process.cwd());
+  const blocks = collectRunnableSql({
+    siteDir,
+    contentDirs: options.contentDirs ?? defaultContentDirs(siteDir),
+  });
+  const requested = options.extension;
+  const extension = requested
+    ? /^https?:\/\//i.test(requested)
+      ? requested
+      : resolve(requested)
+    : defaultExtension(siteDir);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  // No working directory: in a browser DuckDB's file system is the instance's
+  // own memory, so `COPY … TO` / `dfn_file_write_*` never touch the docs tree —
+  // they land in the page and vanish on the next `newPage()`.
+  const results = await runPages(blocks, extension, options, timeoutMs);
+
+  const report: VerifyReport = {
+    blocks: results,
+    asDeclared: results.filter((result) => result.outcome === 'ok' || result.outcome === 'error-as-expected'),
+    unexpected: results.filter(
+      (result) => result.outcome === 'unexpected-error' || result.outcome === 'unexpected-success',
+    ),
+  };
+  if (options.reportFile) {
+    writeFileSync(options.reportFile, `${JSON.stringify(report, null, 2)}\n`);
+  }
+  return report;
+}
+
+/** Opens one page per content file and runs that file's blocks against it. */
+async function runPages(
+  blocks: readonly RunnableSqlBlock[],
+  extension: string,
+  options: VerifyOptions,
+  timeoutMs: number,
+): Promise<BlockResult[]> {
+  const runner = await BrowserSqlRunner.create({
+    extension,
+    platform: options.platform,
+    engine: options.engine,
+    browser: options.browser,
+  });
+  const results: BlockResult[] = [];
+  try {
+    let currentFile: string | null = null;
+    for (const block of blocks) {
+      if (block.file !== currentFile) {
+        currentFile = block.file;
+        await runner.newPage();
+      }
+      results.push(await runBlock(runner, block, timeoutMs));
+    }
+  } finally {
+    await runner.close();
+  }
+  return results;
+}
+
+/** Runs one block and judges the result against the block's own declaration. */
+async function runBlock(
+  runner: BrowserSqlRunner,
+  block: RunnableSqlBlock,
+  timeoutMs: number,
+): Promise<BlockResult> {
+  const declaredError = expectsError(block.config);
+  try {
+    const result = await withTimeout(runner.run(block.sql), timeoutMs);
+    return {
+      file: block.file,
+      line: block.line,
+      outcome: declaredError ? 'unexpected-success' : 'ok',
+      detail: declaredError
+        ? `declared "expect": "error" but succeeded (${result.rows}×${result.columns})`
+        : `ok (${result.rows}×${result.columns})`,
+    };
+  } catch (error) {
+    const message = String((error as Error)?.message ?? error).split('\n')[0] ?? '';
+    return {
+      file: block.file,
+      line: block.line,
+      outcome: declaredError ? 'error-as-expected' : 'unexpected-error',
+      detail: message,
+    };
+  }
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`timed out after ${ms}ms`)), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+/**
+ * Where a Docusaurus site keeps its pages: the English sources in `docs/`, and
+ * each translation under `i18n/<locale>/docusaurus-plugin-content-docs/current/`.
+ */
+function defaultContentDirs(siteDir: string): string[] {
+  const dirs: string[] = [];
+  if (isDirectory(join(siteDir, DEFAULT_CONTENT[0]))) {
+    dirs.push(DEFAULT_CONTENT[0]);
+  }
+  const i18n = join(siteDir, DEFAULT_CONTENT[1]);
+  if (isDirectory(i18n)) {
+    for (const locale of readdirSync(i18n)) {
+      const translated = join(i18n, locale, 'docusaurus-plugin-content-docs', 'current');
+      if (isDirectory(translated)) {
+        dirs.push(join('i18n', locale, 'docusaurus-plugin-content-docs', 'current'));
+      }
+    }
+  }
+  return dirs.length > 0 ? dirs : ['.'];
+}
+
+/** The site's preloaded extension, as `dfkExtensions` places it under `static/`. */
+function defaultExtension(siteDir: string): string {
+  const dir = join(siteDir, 'static', 'duckdb-extensions');
+  const candidates = isDirectory(dir)
+    ? readdirSync(dir).filter((name) => name.endsWith('.duckdb_extension.wasm'))
+    : [];
+  if (candidates.length === 0) {
+    throw new Error(
+      `sql/verify: no extension found in ${dir} — pass --extension <file|url>, or let the site's ` +
+        `extension preload plugin fetch it first`,
+    );
+  }
+  if (candidates.length > 1) {
+    throw new Error(
+      `sql/verify: several extensions found in ${dir} (${candidates.join(', ')}) — ` +
+        `pass --extension to pick one`,
+    );
+  }
+  return join(dir, candidates[0] as string);
+}
+
+function isDirectory(path: string): boolean {
+  return statSync(path, {throwIfNoEntry: false})?.isDirectory() ?? false;
+}
+
+export interface CliOptions extends VerifyOptions {
+  quiet?: boolean;
+}
+
+/**
+ * `duckfn-sql-verify` — the command line around {@link verifySqlDocs}.
+ *
+ * Exit code 1 when a block did not behave as it declared, so a docs site can
+ * wire it straight into `npm test`.
+ */
+export async function cliMain(argv: readonly string[]): Promise<void> {
+  const options = parseArgs(argv);
+  if (options.help) {
+    process.stdout.write(USAGE);
+    return;
+  }
+  const started = Date.now();
+  const report = await verifySqlDocs(options);
+  const seconds = ((Date.now() - started) / 1000).toFixed(1);
+  const declaredFailures = report.blocks.filter(
+    (result) => result.outcome === 'error-as-expected',
+  ).length;
+  if (!options.quiet) {
+    process.stdout.write(`\n${report.blocks.length} block(s) in ${seconds}s\n`);
+    process.stdout.write(
+      `  ${report.asDeclared.length} as declared (${declaredFailures} erroring on purpose), ` +
+        `${report.unexpected.length} unexpected\n`,
+    );
+  }
+  if (report.unexpected.length > 0) {
+    process.stdout.write('unexpected behaviour:\n');
+    for (const block of report.unexpected) {
+      process.stdout.write(`- ${block.file}:${block.line} [${block.outcome}] :: ${block.detail}\n`);
+    }
+    process.exitCode = 1;
+  }
+}
+
+const USAGE = `Usage: duckfn-sql-verify [options]
+
+Runs every runnable SQL block of a duckfn docs site in a headless browser
+(DuckDB-Wasm), and checks that each one behaves as its own metadata declares
+("expect": "error" for a block that demonstrates a failure).
+
+  --site <dir>          Docs site root (default: the working directory)
+  --content <dir>       Content directory, relative to the site root (repeatable;
+                        default: docs/ plus every i18n/<locale>/… translation)
+  --extension <path>    The extension to preload: a .duckdb_extension.wasm path,
+                        or an absolute http(s) URL (default: the single file under
+                        static/duckdb-extensions/)
+  --platform <eh|mvp>   DuckDB-Wasm bundle, which must match the extension build
+                        (default: eh)
+  --engine <path>       Engine wasm override
+  --browser <path>      Browser executable (default: a detected Chrome/Edge,
+                        or the DFK_BROWSER environment variable)
+  --timeout <ms>        Per-block timeout (default: 30000)
+  --report <file>       Write the full result list as JSON
+  --quiet               Only report unexpected behaviour
+  --help                Show this help
+`;
+
+interface ParsedArgs extends CliOptions {
+  help?: boolean;
+}
+
+function parseArgs(argv: readonly string[]): ParsedArgs {
+  const options: ParsedArgs = {};
+  const content: string[] = [];
+  for (let index = 0; index < argv.length; index++) {
+    const arg = argv[index];
+    const next = (): string => {
+      const value = argv[++index];
+      if (value === undefined) {
+        throw new Error(`sql/verify: ${arg} needs a value`);
+      }
+      return value;
+    };
+    switch (arg) {
+      case '--site':
+        options.siteDir = next();
+        break;
+      case '--content':
+        content.push(next());
+        break;
+      case '--extension':
+        options.extension = next();
+        break;
+      case '--platform':
+        options.platform = next() as WasmPlatform;
+        break;
+      case '--engine':
+        options.engine = next();
+        break;
+      case '--browser':
+        options.browser = next();
+        break;
+      case '--timeout':
+        options.timeoutMs = Number(next());
+        break;
+      case '--report':
+        options.reportFile = next();
+        break;
+      case '--quiet':
+        options.quiet = true;
+        break;
+      case '--help':
+      case '-h':
+        options.help = true;
+        break;
+      default:
+        throw new Error(`sql/verify: unknown option ${arg}`);
+    }
+  }
+  if (content.length > 0) {
+    options.contentDirs = content;
+  }
+  return options;
+}