claude: add QUARTO_PDF_STANDARD env var and pdf analysis tools

Add environment variable fallback for pdf-standard option so any
document without an explicit pdf-standard setting inherits from
QUARTO_PDF_STANDARD (comma-separated, e.g. "ua-1" or "a-2b,ua-1").

Also add tools/find-tests.ts to find test documents by format
and tools/filter-pdf-errors.ts to extract and summarize PDF
validation errors from render logs.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: gordonwoodhull

src/command/render/output-tex.ts

@@ -18,6 +18,7 @@ import {
   kPdfStandard,
   kPdfStandardApplied,
   kTargetFormat,
+  pdfStandardEnv,
 } from "../../config/constants.ts";
 import { Format } from "../../config/types.ts";
 import { asArray } from "../../core/array.ts";
@@ -90,7 +91,8 @@ export function texToPdfOutputRecipe(
     const pdfStandards = asArray(
       pandocOptions.format.metadata?.[kPdfStandardApplied] ??
         format.render?.[kPdfStandard] ??
-        format.metadata?.[kPdfStandard],
+        format.metadata?.[kPdfStandard] ??
+        pdfStandardEnv(),
     ) as string[];
     if (pdfStandards.length > 0) {
       await validatePdfStandards(pdfOutput, pdfStandards, {

src/command/render/output-typst.ts

@@ -34,6 +34,7 @@ import {
   kOutputFile,
   kPdfStandard,
   kVariant,
+  pdfStandardEnv,
 } from "../../config/constants.ts";
 import { error, warning } from "../../deno_ral/log.ts";
 import { ErrorEx } from "../../core/lib/error.ts";
@@ -158,7 +159,8 @@ export function typstPdfOutputRecipe(
       ),
       pdfStandard: normalizePdfStandardForTypst(
         asArray(
-          format.render?.[kPdfStandard] ?? format.metadata?.[kPdfStandard],
+          format.render?.[kPdfStandard] ?? format.metadata?.[kPdfStandard] ??
+            pdfStandardEnv(),
         ),
       ),
     };
@@ -185,7 +187,8 @@ export function typstPdfOutputRecipe(
 
     // Validate PDF against specified standards using verapdf (if available)
     const pdfStandards = asArray(
-      format.render?.[kPdfStandard] ?? format.metadata?.[kPdfStandard],
+      format.render?.[kPdfStandard] ?? format.metadata?.[kPdfStandard] ??
+        pdfStandardEnv(),
     ) as string[];
     if (pdfStandards.length > 0) {
       await validatePdfStandards(pdfOutput, pdfStandards, {

src/config/constants.ts

@@ -88,6 +88,15 @@ export const kKeepTex = "keep-tex";
 export const kKeepTyp = "keep-typ";
 export const kPdfStandard = "pdf-standard";
 export const kPdfStandardApplied = "pdf-standard-applied";
+
+/** Read QUARTO_PDF_STANDARD env var as a fallback for pdf-standard option. */
+export function pdfStandardEnv(): string[] | undefined {
+  const val = Deno.env.get("QUARTO_PDF_STANDARD");
+  if (val) {
+    return val.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+  }
+  return undefined;
+}
 export const kKeepIpynb = "keep-ipynb";
 export const kKeepSource = "keep-source";
 export const kVariant = "variant";

src/format/pdf/format-pdf.ts

@@ -38,6 +38,7 @@ import {
   kTblCapLoc,
   kTopLevelDivision,
   kWarning,
+  pdfStandardEnv,
 } from "../../config/constants.ts";
 import { warning } from "../../deno_ral/log.ts";
 import { asArray } from "../../core/array.ts";
@@ -326,7 +327,8 @@ function createPdfFormat(
 
         // Handle pdf-standard option for PDF/A, PDF/UA, PDF/X conformance
         const pdfStandard = asArray(
-          format.render?.[kPdfStandard] ?? format.metadata?.[kPdfStandard],
+          format.render?.[kPdfStandard] ?? format.metadata?.[kPdfStandard] ??
+            pdfStandardEnv(),
         );
         if (pdfStandard.length > 0) {
           const { version, standards, needsTagging } =

tools/filter-pdf-errors.ts

@@ -0,0 +1,233 @@
+#!/usr/bin/env -S quarto run
+/**
+ * filter-pdf-errors.ts
+ *
+ * Parse a quarto render log and extract PDF validation errors,
+ * showing which files failed and why. Aggregates errors by type at the end.
+ *
+ * Handles two error formats:
+ *   - Typst compiler errors: "error: PDF/UA-1 error: missing alt text"
+ *   - verapdf validation failures: "WARN: PDF validation failed for ua-2:\n<rule text>"
+ *
+ * Usage:
+ *   quarto run tools/filter-pdf-errors.ts <logfile>
+ *
+ * Reads from stdin if no file is given.
+ */
+
+// Strip ANSI escape codes
+function stripAnsi(s: string): string {
+  return s.replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+// Unescape HTML entities from verapdf output
+function unescapeHtml(s: string): string {
+  return s
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&amp;/g, "&")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'");
+}
+
+interface RenderBlock {
+  inputFile: string;
+  outputFile: string;
+  lines: string[];
+}
+
+interface ErrorEntry {
+  file: string;
+  errorType: string;
+  context: string[];
+}
+
+function extractErrors(block: RenderBlock): {
+  seenErrors: Set<string>;
+  context: string[];
+} {
+  const context: string[] = [];
+  let inStack = false;
+  const seenErrors = new Set<string>();
+
+  for (let i = 0; i < block.lines.length; i++) {
+    const line = block.lines[i];
+
+    // Skip download lines
+    if (/^Download /.test(line.trim())) continue;
+    // Skip blank-ish lines at start
+    if (context.length === 0 && line.trim() === "") continue;
+
+    // Detect start of stack trace
+    if (/^Stack trace:/.test(line.trim())) {
+      inStack = true;
+      continue;
+    }
+    if (inStack) {
+      if (/^\s+at /.test(line)) continue;
+      inStack = false;
+    }
+
+    // Skip duplicate ERROR: lines from typst
+    if (/^ERROR: error: PDF\//.test(line.trim())) continue;
+    if (/^ERROR: Typst compilation failed/.test(line.trim())) continue;
+
+    // Typst compiler errors: "error: PDF/UA-1 error: missing alt text"
+    const typstMatch = line.match(/error: (PDF\/\S+ error: .+)/);
+    if (typstMatch) {
+      const errType = typstMatch[1].trim();
+      seenErrors.add(errType);
+    }
+
+    // verapdf failures: "WARN: PDF validation failed for <standard>:"
+    // followed by one or more rule description lines until a blank line or "Output created"
+    const verapdfMatch = line.match(
+      /^WARN: PDF validation failed for ([\w-]+):$/,
+    );
+    if (verapdfMatch) {
+      const standard = verapdfMatch[1];
+      // Collect the rule lines that follow
+      for (let j = i + 1; j < block.lines.length; j++) {
+        const ruleLine = block.lines[j].trim();
+        if (ruleLine === "" || /^Output created/.test(ruleLine)) break;
+        const errType = `${standard}: ${ruleLine}`;
+        seenErrors.add(errType);
+      }
+    }
+
+    context.push(line);
+  }
+
+  // Trim trailing blank lines
+  while (context.length > 0 && context[context.length - 1].trim() === "") {
+    context.pop();
+  }
+
+  return { seenErrors, context };
+}
+
+async function main() {
+  const path = Deno.args[0];
+  let text: string;
+  if (path) {
+    text = await Deno.readTextFile(path);
+  } else {
+    const buf = await new Response(Deno.stdin.readable).text();
+    text = buf;
+  }
+
+  const rawLines = text.split("\n");
+  const lines = rawLines.map((l) => unescapeHtml(stripAnsi(l)));
+
+  // Parse into render blocks. Each block starts with either a
+  // "Rendering <path>.qmd" line or a "pandoc" header.
+  const blocks: RenderBlock[] = [];
+  let current: RenderBlock | null = null;
+  let pendingInputFile = "";
+
+  for (const line of lines) {
+    // "Rendering docs/smoke-all/.../foo.qmd" precedes the pandoc block
+    const renderMatch = line.match(/^Rendering\s+(\S+\.qmd)\s*$/);
+    if (renderMatch) {
+      pendingInputFile = renderMatch[1];
+      continue;
+    }
+
+    if (/^pandoc\s*$/.test(line.trim())) {
+      if (current) blocks.push(current);
+      current = { inputFile: pendingInputFile, outputFile: "", lines: [] };
+      pendingInputFile = "";
+      current.lines.push(line);
+      continue;
+    }
+    if (current) {
+      current.lines.push(line);
+      const m = line.match(/^\s*output-file:\s*(.+)/);
+      if (m) {
+        current.outputFile = m[1].trim();
+      }
+    }
+  }
+  if (current) blocks.push(current);
+
+  // Extract errors from each block
+  const errors: ErrorEntry[] = [];
+  const errorCounts = new Map<string, number>();
+  const errorFiles = new Map<string, string[]>();
+
+  for (const block of blocks) {
+    // Check for either error format
+    const hasError = block.lines.some(
+      (l) =>
+        l.includes("error: PDF/") ||
+        l.includes("ERROR: error: PDF/") ||
+        l.includes("PDF validation failed"),
+    );
+    if (!hasError) continue;
+
+    const { seenErrors, context } = extractErrors(block);
+    const displayFile = block.inputFile || block.outputFile;
+
+    for (const errType of seenErrors) {
+      errorCounts.set(errType, (errorCounts.get(errType) || 0) + 1);
+      const files = errorFiles.get(errType) || [];
+      if (!files.includes(displayFile)) {
+        files.push(displayFile);
+      }
+      errorFiles.set(errType, files);
+
+      errors.push({
+        file: displayFile,
+        errorType: errType,
+        context,
+      });
+    }
+  }
+
+  // Print per-file errors
+  const printedFiles = new Set<string>();
+  for (const err of errors) {
+    if (printedFiles.has(err.file)) continue;
+    printedFiles.add(err.file);
+
+    const fileErrors = errors.filter((e) => e.file === err.file);
+    const types = [...new Set(fileErrors.map((e) => e.errorType))];
+
+    console.log("─".repeat(72));
+    console.log(`FILE: ${err.file}`);
+    console.log(`ERRORS: ${types.join(", ")}`);
+    console.log("");
+    for (const line of err.context) {
+      console.log("  " + line);
+    }
+    console.log("");
+  }
+
+  // Print summary
+  console.log("═".repeat(72));
+  console.log("SUMMARY");
+  console.log("═".repeat(72));
+  console.log("");
+  console.log(`Total files with errors: ${printedFiles.size}`);
+  console.log(`Total files rendered:    ${blocks.length}`);
+  console.log("");
+
+  // Sort by count descending
+  const sorted = [...errorCounts.entries()].sort((a, b) => b[1] - a[1]);
+  for (const [errType, count] of sorted) {
+    console.log(`  ${count.toString().padStart(4)}  ${errType}`);
+  }
+  console.log("");
+
+  // List files per error type
+  for (const [errType] of sorted) {
+    const files = errorFiles.get(errType) || [];
+    console.log(`${errType} (${files.length} files):`);
+    for (const f of files) {
+      console.log(`  - ${f}`);
+    }
+    console.log("");
+  }
+}
+
+main();

tools/find-tests.ts

@@ -0,0 +1,80 @@
+/**
+ * find-tests.ts
+ *
+ * Find all .qmd files under a directory that target a given format.
+ *
+ * Usage:
+ *   quarto run --dev tools/find-tests.ts <format> <directory>
+ *
+ * A document matches if the format name appears as:
+ *   - The value of `format:` (string) in its YAML front matter
+ *   - A key under `format:` (object) in its YAML front matter
+ *   - A key under `_quarto.tests:` in its YAML front matter
+ */
+
+import { walk } from "../src/deno_ral/fs.ts";
+import { readYamlFromMarkdown, readYaml } from "../src/core/yaml.ts";
+import { dirname, join, relative } from "../src/deno_ral/path.ts";
+import { existsSync } from "../src/deno_ral/fs.ts";
+
+const [format, dir] = Deno.args;
+if (!format || !dir) {
+  console.error("Usage: quarto run tools/find-tests.ts <format> <directory>");
+  Deno.exit(1);
+}
+
+function hasFormat(
+  yaml: Record<string, unknown>,
+  format: string,
+): boolean {
+  // Check format: <string> or format: { <format>: ... }
+  const fmt = yaml["format"];
+  if (typeof fmt === "string" && fmt === format) {
+    return true;
+  }
+  if (fmt && typeof fmt === "object" && format in (fmt as Record<string, unknown>)) {
+    return true;
+  }
+
+  // Check _quarto.tests.<format>
+  const quarto = yaml["_quarto"] as Record<string, unknown> | undefined;
+  if (quarto) {
+    const tests = quarto["tests"] as Record<string, unknown> | undefined;
+    if (tests && format in tests) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+for await (const entry of walk(dir, { exts: [".qmd"], includeDirs: false })) {
+  try {
+    const content = Deno.readTextFileSync(entry.path);
+    const yaml = readYamlFromMarkdown(content) as Record<string, unknown>;
+    if (hasFormat(yaml, format)) {
+      console.log(relative(Deno.cwd(), entry.path));
+      continue;
+    }
+
+    // Check _quarto.yml in the same directory and ancestors up to dir
+    let current = dirname(entry.path);
+    const root = Deno.realPathSync(dir);
+    while (true) {
+      const quartoYml = join(current, "_quarto.yml");
+      if (existsSync(quartoYml)) {
+        const projYaml = readYaml(quartoYml) as Record<string, unknown>;
+        if (hasFormat(projYaml, format)) {
+          console.log(relative(Deno.cwd(), entry.path));
+          break;
+        }
+      }
+      if (Deno.realPathSync(current) === root) break;
+      const parent = dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+  } catch {
+    // skip files that can't be parsed
+  }
+}