duckfn-docs-kit 0.1.0 → 0.2.1

package/src/sql/verify.ts

@@ -0,0 +1,357 @@
+/**
+ * `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 worker,
+ * the site's extension preloaded, one instance per page and the page's blocks
+ * sharing a connection (see `sql/nodeRunner.ts` for why it is this target and
+ * not the blocking one).
+ *
+ * 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 {mkdirSync, mkdtempSync, readdirSync, rmSync, statSync, writeFileSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join, resolve} from 'node:path';
+
+import {collectRunnableSql, expectsError, type RunnableSqlBlock} from './collect';
+import {WasmSqlRunner, type WasmPlatform} from './nodeRunner';
+
+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;
+  /**
+   * Directory the blocks run in. Defaults to a fresh temporary directory that
+   * is removed afterwards: a block may `COPY … TO 'a.csv'`, and on Node
+   * DuckDB's file system is the real one, relative to the working directory.
+   */
+  workingDir?: 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> {
+  // Everything is resolved to absolute paths first: the run changes the working
+  // directory (see below).
+  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;
+
+  // A block may write files — `COPY (SELECT 1) TO 'a.csv'` — and on Node the
+  // file system behind DuckDB is the real one, resolved against the working
+  // directory. Giving the run a scratch directory of its own keeps the docs tree
+  // clean instead of dropping test residue into it.
+  const scratch = options.workingDir
+    ? resolve(options.workingDir)
+    : mkdtempSync(join(tmpdir(), 'duckfn-sql-verify-'));
+  mkdirSync(scratch, {recursive: true});
+  const previousCwd = process.cwd();
+  process.chdir(scratch);
+
+  let results: BlockResult[];
+  try {
+    results = await runPages(blocks, extension, options, timeoutMs);
+  } finally {
+    process.chdir(previousCwd);
+    if (!options.workingDir) {
+      rmSync(scratch, {recursive: true, force: true});
+    }
+  }
+
+  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 WasmSqlRunner.create({
+    extension,
+    platform: options.platform,
+    engine: options.engine,
+  });
+  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: WasmSqlRunner,
+  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 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
+  --timeout <ms>        Per-block timeout (default: 30000)
+  --working-dir <dir>   Directory the blocks run in (default: a temporary one)
+  --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 '--timeout':
+        options.timeoutMs = Number(next());
+        break;
+      case '--working-dir':
+        options.workingDir = 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;
+}

package/src/toc-toggle/TocToggle.css

@@ -54,6 +54,28 @@ body.toc-collapsed .toc-toggle::after {
    order wins over specificity — an unlayered `!important` loses to a layered
    one, so the `max-width` below would silently do nothing outside this layer. */
 @layer docusaurus.theme-classic {
+  /* The button sits in the column above the TOC, while only the TOC is sticky
+     (`DocItem/TOC` styles make it so). On any page taller than the viewport the
+     button therefore scrolls away and the TOC cannot be collapsed back — so it
+     is pinned here, and the TOC's own `top`/`max-height` are pushed down by the
+     button's height plus its margin, which is what keeps the two from
+     overlapping. The `top` values follow the theme's
+     `calc(var(--ifm-navbar-height) + 1rem)`.
+
+     Written with the `.toc-column` prefix for specificity: the TOC's rule comes
+     from a CSS module's hashed class at the same layer, so an equal-specificity
+     rule here would depend on stylesheet order. */
+  .toc-column .toc-toggle {
+    position: sticky;
+    top: calc(var(--ifm-navbar-height) + 0.5rem);
+    z-index: 1;
+  }
+
+  .toc-column .theme-doc-toc-desktop {
+    top: calc(var(--ifm-navbar-height) + 3rem);
+    max-height: calc(100vh - (var(--ifm-navbar-height) + 4rem));
+  }
+
   body.toc-collapsed .toc-column {
     --ifm-col-width: 2.5rem;
     padding: 0;
@@ -63,6 +85,12 @@ body.toc-collapsed .toc-toggle::after {
     display: none;
   }
 
+  /* Collapsed, the strip is 2.5rem wide and only the button is left in it: it
+     centres instead of hugging the right edge of a column it no longer fills. */
+  body.toc-collapsed .toc-toggle {
+    margin-inline: auto;
+  }
+
   body.toc-collapsed [class*='docItemCol'] {
     max-width: 100% !important;
   }