@capagents/forgeqe 1.1.3 → 1.1.4

package/src/bi.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process"
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { copyFileSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs"
 import path from "node:path"
 
 import type { Readiness } from "./cases/readiness.ts"
@@ -7,11 +7,32 @@ import { adoSettings } from "./cases/ado.ts"
 import { FAILURE_ACTION } from "./cases/failure.ts"
 import { http } from "./cases/http.ts"
 import { jiraApi } from "./cases/jira.ts"
-import { cachedJson } from "./cache.ts"
 import type { CaseResult, WriteBack } from "./cases/types.ts"
 import type { AppConfig, BiConfig, BiDatasetConfig } from "./config.ts"
+import { reportHtml } from "./mcp/reporttools.ts"
+import { duration } from "./report/html.ts"
 import { counts as suiteCounts } from "./suite/report.ts"
 
+/**
+ * forgeqe bi: CSV datasets from ForgeQE's own reports (and optional ADO/Jira queries), rendered as a static site.
+ * The site is built with the open-source Evidence line (@evidence-dev/evidence 40.x, CSV source, pinned below):
+ * the current Evidence Studio CLI has no local build and keeps data in its cloud. When Node/npm is missing or the
+ * Evidence build fails, ForgeQE writes its own self-contained page from the same data instead.
+ */
+
+/** The legacy Evidence packages the generated project installs; exact versions so builds are repeatable. */
+const EVIDENCE_PACKAGES = {
+  "@evidence-dev/core-components": "5.4.2",
+  "@evidence-dev/csv": "1.0.16",
+  "@evidence-dev/evidence": "40.1.8",
+}
+/** Evidence names each CSV's table after its file, under this source: forgeqe.suites, forgeqe.<dataset id>. */
+const SOURCE = "forgeqe"
+/** In the front matter of every page ForgeQE owns; a page without it is the team's and is never overwritten. */
+const MANAGED = "# Managed by forgeqe bi: regenerated on every sync."
+/** ADO's WIQL limit: a query that returns this many items was probably cut off. */
+const ADO_WIQL_MAX = 20000
+
 type BuildOverrides = { evidenceDir?: string; dataDir?: string; buildDir?: string }
 type Paths = {
   evidenceDir: string
@@ -19,7 +40,6 @@ type Paths = {
   buildDir: string
   sourceDir: string
   pagesDir: string
-  externalDataDir: string
 }
 
 type SuiteFile = {
@@ -150,7 +170,10 @@ type ExternalDatasetRow = {
   page: string
 }
 
-type ExternalExport = { row: ExternalDatasetRow; files: string[] }
+type ExternalExport = { row: ExternalDatasetRow; headers: readonly string[]; rows: Record<string, unknown>[] }
+
+type SuiteData = { suites: SuiteRow[]; cases: CaseRow[]; steps: StepRow[]; writebacks: WriteBackRow[] }
+type ReadinessData = { summary: ReadinessRow[]; stories: ReadinessStoryRow[]; cases: ReadinessCaseRow[] }
 
 export type BiSyncResult = {
   evidenceDir: string
@@ -163,77 +186,132 @@ export type BiSyncResult = {
   dataFiles: string[]
   pageFiles: string[]
   summaryFile: string
+  /** Things the user should know: a project ForgeQE did not create, a dataset that hit a limit. */
+  notes: string[]
 }
 
-export type BiBuildResult = BiSyncResult & { indexFile: string }
+/** evidence: the Evidence site was built; static: ForgeQE's own page, because Evidence could not build (or was not asked). */
+export type BiEngine = "auto" | "evidence" | "static"
+
+export type BiBuildResult = BiSyncResult & { indexFile: string; engine: "evidence" | "static"; fallbackReason?: string }
+
+/** Runs one command (npm, npx) in a folder; tests replace it. */
+type CommandRunner = (command: string, args: string[], cwd: string) => Promise<void>
+let runnerOverride: CommandRunner | undefined
 
-export async function initBiProject(cfg: AppConfig, overrides: BuildOverrides = {}): Promise<{ evidenceDir: string; files: string[] }> {
-  const paths = resolvePaths(cfg.bi || defaultBiConfig(cfg), overrides)
-  await ensureEvidenceProject(paths.evidenceDir)
-  const files = writeManagedEvidenceFiles(cfg, paths)
-  return { evidenceDir: paths.evidenceDir, files }
+export function setBiRunnerForTests(runner?: CommandRunner): void {
+  runnerOverride = runner
 }
 
-export async function syncBiData(cfg: AppConfig, overrides: BuildOverrides = {}): Promise<BiSyncResult> {
+export async function initBiProject(cfg: AppConfig, overrides: BuildOverrides = {}): Promise<{ evidenceDir: string; files: string[]; notes: string[] }> {
   const bi = cfg.bi || defaultBiConfig(cfg)
   const paths = resolvePaths(bi, overrides)
-  await ensureEvidenceProject(paths.evidenceDir)
-  const pageFiles = writeManagedEvidenceFiles({ ...cfg, bi }, paths)
+  const notes: string[] = []
+  const files = [...scaffoldEvidenceProject(paths, notes), ...writeManagedEvidenceFiles(bi, paths, new Set())]
+  try {
+    await installEvidence(paths)
+  } catch (err) {
+    notes.push(`Evidence packages not installed (${errorText(err)}); forgeqe bi build will try again, or write ForgeQE's own page.`)
+  }
+  return { evidenceDir: paths.evidenceDir, files, notes }
+}
 
-  mkdirSync(paths.dataDir, { recursive: true })
-  mkdirSync(paths.buildDir, { recursive: true })
-  mkdirSync(paths.externalDataDir, { recursive: true })
+export async function syncBiData(cfg: AppConfig, overrides: BuildOverrides = {}): Promise<BiSyncResult> {
+  return (await syncData(cfg, overrides)).result
+}
+
+async function syncData(cfg: AppConfig, overrides: BuildOverrides): Promise<{ result: BiSyncResult; bi: BiConfig; paths: Paths; suites: SuiteData; readiness: ReadinessData; external: ExternalExport[] }> {
+  const bi = cfg.bi || defaultBiConfig(cfg)
+  const paths = resolvePaths(bi, overrides)
+  const notes: string[] = []
+  for (const dir of [paths.dataDir, paths.sourceDir, paths.buildDir]) mkdirSync(dir, { recursive: true })
 
   const suites = collectSuiteData(cfg)
   const readiness = collectReadiness(cfg)
-  const external = await exportExternalDatasets({ ...cfg, bi }, paths)
-
-  const dataFiles = [
-    writeCsv(path.join(paths.dataDir, "suites.csv"), SUITE_HEADERS, suites.suites),
-    writeCsv(path.join(paths.dataDir, "case_results.csv"), CASE_HEADERS, suites.cases),
-    writeCsv(path.join(paths.dataDir, "step_results.csv"), STEP_HEADERS, suites.steps),
-    writeCsv(path.join(paths.dataDir, "writebacks.csv"), WRITEBACK_HEADERS, suites.writebacks),
-    writeCsv(path.join(paths.dataDir, "readiness.csv"), READINESS_HEADERS, readiness.summary),
-    writeCsv(path.join(paths.dataDir, "readiness_stories.csv"), READINESS_STORY_HEADERS, readiness.stories),
-    writeCsv(path.join(paths.dataDir, "readiness_cases.csv"), READINESS_CASE_HEADERS, readiness.cases),
-    writeCsv(path.join(paths.dataDir, "external_datasets.csv"), EXTERNAL_HEADERS, external.map((e) => e.row)),
-    ...external.flatMap((e) => e.files),
+  const external = await exportExternalDatasets({ ...cfg, bi }, notes)
+
+  const tables: { name: string; headers: readonly string[]; rows: Record<string, unknown>[] }[] = [
+    { name: "suites", headers: SUITE_HEADERS, rows: suites.suites },
+    { name: "case_results", headers: CASE_HEADERS, rows: suites.cases },
+    { name: "step_results", headers: STEP_HEADERS, rows: suites.steps },
+    { name: "writebacks", headers: WRITEBACK_HEADERS, rows: suites.writebacks },
+    { name: "readiness", headers: READINESS_HEADERS, rows: readiness.summary },
+    { name: "readiness_stories", headers: READINESS_STORY_HEADERS, rows: readiness.stories },
+    { name: "readiness_cases", headers: READINESS_CASE_HEADERS, rows: readiness.cases },
+    { name: "external_datasets", headers: EXTERNAL_HEADERS, rows: external.map((e) => e.row) },
+    ...external.map((e) => ({ name: e.row.dataset_id, headers: e.headers, rows: e.rows })),
   ]
+  // Evidence's CSV source reads every CSV in its own folder (a data_dir elsewhere is copied there), and it cannot
+  // build over a table with no rows: empty tables stay out of that folder, and their page sections say "None yet.".
+  const separate = path.resolve(paths.dataDir) !== path.resolve(paths.sourceDir)
+  const dataFiles: string[] = []
+  const has = new Set<string>()
+  for (const t of tables) {
+    const file = path.join(paths.dataDir, `${t.name}.csv`)
+    const inSource = path.join(paths.sourceDir, `${t.name}.csv`)
+    if (t.rows.length) has.add(t.name)
+    if (t.rows.length || separate) dataFiles.push(writeCsv(file, t.headers, t.rows))
+    else rmSync(file, { force: true })
+    if (separate) {
+      if (t.rows.length) copyFileSync(file, inSource)
+      else rmSync(inSource, { force: true })
+    }
+  }
+  const pageFiles = [...scaffoldEvidenceProject(paths, notes), ...writeManagedEvidenceFiles(bi, paths, has)]
 
   const summaryFile = path.join(paths.buildDir, "summary.md")
-  writeFileSync(summaryFile, summaryMarkdown({ ...cfg, bi }, paths, suites, readiness, external), "utf8")
+  writeFileSync(summaryFile, summaryMarkdown(bi, paths, suites, readiness, external), "utf8")
 
   return {
-    evidenceDir: paths.evidenceDir,
-    dataDir: paths.dataDir,
-    buildDir: paths.buildDir,
-    suites: suites.suites.length,
-    caseResults: suites.cases.length,
-    readinessReports: readiness.summary.length,
-    externalDatasets: external.length,
-    dataFiles,
-    pageFiles,
-    summaryFile,
+    result: {
+      evidenceDir: paths.evidenceDir,
+      dataDir: paths.dataDir,
+      buildDir: paths.buildDir,
+      suites: suites.suites.length,
+      caseResults: suites.cases.length,
+      readinessReports: readiness.summary.length,
+      externalDatasets: external.length,
+      dataFiles,
+      pageFiles,
+      summaryFile,
+      notes,
+    },
+    bi,
+    paths,
+    suites,
+    readiness,
+    external,
   }
 }
 
-export async function buildBi(cfg: AppConfig, overrides: BuildOverrides = {}): Promise<BiBuildResult> {
-  const synced = await syncBiData(cfg, overrides)
-  await runEvidence(["build"], synced.evidenceDir, { EVIDENCE_BUILD_DIR: synced.buildDir })
-  return { ...synced, indexFile: path.join(synced.buildDir, "index.html") }
+export async function buildBi(cfg: AppConfig, overrides: BuildOverrides = {}, engine: BiEngine = "auto"): Promise<BiBuildResult> {
+  const synced = await syncData(cfg, overrides)
+  const indexFile = path.join(synced.paths.buildDir, "index.html")
+  const writeStatic = (reason: string): BiBuildResult => {
+    writeFileSync(indexFile, staticReport(synced.bi, synced.paths, synced.suites, synced.readiness, synced.external, reason), "utf8")
+    return { ...synced.result, indexFile, engine: "static", fallbackReason: reason }
+  }
+  if (engine === "static") return writeStatic("asked for with --static")
+  try {
+    await buildWithEvidence(synced.paths)
+    return { ...synced.result, indexFile, engine: "evidence" }
+  } catch (err) {
+    if (engine === "evidence") throw err
+    return writeStatic(errorText(err))
+  }
 }
 
 function resolvePaths(cfg: BiConfig, overrides: BuildOverrides): Paths {
   const evidenceDir = path.resolve(overrides.evidenceDir || cfg.evidenceDir)
-  const dataDir = path.resolve(overrides.dataDir || cfg.dataDir)
-  const buildDir = path.resolve(overrides.buildDir || cfg.buildDir)
+  const sourceDir = path.join(evidenceDir, "sources", SOURCE)
+  // A new evidence dir from the command line carries its own data folder unless one is given too.
+  const dataDir = path.resolve(overrides.dataDir || (overrides.evidenceDir ? sourceDir : cfg.dataDir))
   return {
     evidenceDir,
     dataDir,
-    buildDir,
-    sourceDir: path.join(evidenceDir, "sources", "forgeqe"),
+    buildDir: path.resolve(overrides.buildDir || cfg.buildDir),
+    sourceDir,
     pagesDir: path.join(evidenceDir, "pages"),
-    externalDataDir: path.join(dataDir, "external"),
   }
 }
 
@@ -242,231 +320,161 @@ function defaultBiConfig(cfg: AppConfig): BiConfig {
   return {
     title: "ForgeQE BI",
     evidenceDir,
-    dataDir: path.join(evidenceDir, "sources", "forgeqe", "data"),
+    dataDir: path.join(evidenceDir, "sources", SOURCE),
     buildDir: path.join(cfg.export.outDir, "bi"),
     datasets: [],
   }
 }
 
-async function ensureEvidenceProject(dir: string): Promise<void> {
-  if (existsSync(path.join(dir, "evidence.config.yaml"))) return
-  mkdirSync(path.dirname(dir), { recursive: true })
-  await runEvidence(["init", dir], process.cwd())
+/** The Evidence project's own files, written only when missing so a team's changes to them are kept. */
+function scaffoldEvidenceProject(paths: Paths, notes: string[]): string[] {
+  const files: string[] = []
+  const missing = (name: string) => !existsSync(path.join(paths.evidenceDir, name))
+  const pkg = {
+    name: "forgeqe-bi",
+    version: "0.0.1",
+    private: true,
+    type: "module",
+    scripts: { sources: "evidence sources", build: "evidence build", dev: "evidence dev", preview: "evidence preview" },
+    engines: { node: ">=18.0.0" },
+    dependencies: EVIDENCE_PACKAGES,
+    // Evidence 40.1.8 peers on TypeScript 5.4.2 exactly; without this pin npm resolves 7.x and refuses to install.
+    devDependencies: { typescript: "5.4.2" },
+  }
+  if (missing("package.json")) files.push(writeText(path.join(paths.evidenceDir, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`))
+  if (missing(".npmrc")) files.push(writeText(path.join(paths.evidenceDir, ".npmrc"), "loglevel=error\naudit=false\nfund=false\n"))
+  if (missing(".gitignore")) files.push(writeText(path.join(paths.evidenceDir, ".gitignore"), "node_modules/\nbuild/\n.evidence/template/\n"))
+  const configFile = path.join(paths.evidenceDir, "evidence.config.yaml")
+  if (!existsSync(configFile)) {
+    files.push(
+      writeText(
+        configFile,
+        [
+          "plugins:",
+          "  components:",
+          '    "@evidence-dev/core-components": {}',
+          "  datasources:",
+          '    "@evidence-dev/csv": {}',
+          "",
+        ].join("\n"),
+      ),
+    )
+  } else if (!readFileSync(configFile, "utf8").includes("@evidence-dev/csv")) {
+    notes.push(`${configFile} does not load the @evidence-dev/csv source; add it under plugins.datasources so Evidence reads ForgeQE's CSV files.`)
+  }
+  return files
 }
 
-function writeManagedEvidenceFiles(cfg: AppConfig, paths: Paths): string[] {
-  const bi = cfg.bi || defaultBiConfig(cfg)
+/** has: the tables with rows; Evidence cannot build a page over an empty table, so those sections say so instead. */
+function writeManagedEvidenceFiles(bi: BiConfig, paths: Paths, has: Set<string>): string[] {
   mkdirSync(paths.sourceDir, { recursive: true })
   mkdirSync(paths.pagesDir, { recursive: true })
-
-  const files: string[] = []
-  files.push(writeText(path.join(paths.sourceDir, "connection.yaml"), `name: forgeqe\ntype: duckdb\noptions:\n  filename: ":memory:"\n`))
-
-  const rel = (file: string) => sqlPath(path.relative(paths.sourceDir, file))
-  const managedQueries: Array<[string, string]> = [
-    ["suites.sql", `select * from read_csv_auto('${rel(path.join(paths.dataDir, "suites.csv"))}', header = true)`],
-    ["case_results.sql", `select * from read_csv_auto('${rel(path.join(paths.dataDir, "case_results.csv"))}', header = true)`],
-    ["step_results.sql", `select * from read_csv_auto('${rel(path.join(paths.dataDir, "step_results.csv"))}', header = true)`],
-    ["writebacks.sql", `select * from read_csv_auto('${rel(path.join(paths.dataDir, "writebacks.csv"))}', header = true)`],
-    ["readiness.sql", `select * from read_csv_auto('${rel(path.join(paths.dataDir, "readiness.csv"))}', header = true)`],
-    ["readiness_stories.sql", `select * from read_csv_auto('${rel(path.join(paths.dataDir, "readiness_stories.csv"))}', header = true)`],
-    ["readiness_cases.sql", `select * from read_csv_auto('${rel(path.join(paths.dataDir, "readiness_cases.csv"))}', header = true)`],
-    ["external_datasets.sql", `select * from read_csv_auto('${rel(path.join(paths.dataDir, "external_datasets.csv"))}', header = true)`],
-  ]
-  for (const dataset of bi.datasets) {
-    managedQueries.push([`${dataset.id}.sql`, `select * from read_csv_auto('${rel(path.join(paths.externalDataDir, `${dataset.id}.csv`))}', header = true)`])
-  }
-  for (const [name, sql] of managedQueries) files.push(writeText(path.join(paths.sourceDir, name), `${sql}\n`))
-
-  files.push(writeText(path.join(paths.pagesDir, "home.md"), homePage({ ...cfg, bi })))
-  files.push(writeText(path.join(paths.pagesDir, "forgeqe-runs.md"), runsPage()))
-  files.push(writeText(path.join(paths.pagesDir, "forgeqe-readiness.md"), readinessPage()))
-  files.push(writeText(path.join(paths.pagesDir, "forgeqe-external.md"), externalPage()))
-  for (const dataset of bi.datasets) {
-    files.push(writeText(path.join(paths.pagesDir, `forgeqe-dataset-${dataset.id}.md`), datasetPage(dataset)))
+  const files = [writeText(path.join(paths.sourceDir, "connection.yaml"), `name: ${SOURCE}\ntype: csv\noptions: {}\n`)]
+  // Evidence reads front matter only at the top of a page, so the marker is a YAML comment there; title names the page in the menu.
+  const page = (name: string, title: string, body: string) => {
+    const file = path.join(paths.pagesDir, name)
+    if (existsSync(file) && !readFileSync(file, "utf8").split("\n", 3).includes(MANAGED)) return
+    files.push(writeText(file, `---\n${MANAGED}\ntitle: ${JSON.stringify(title)}\n---\n\n${body}`))
   }
+  page("index.md", bi.title, homePage(bi, has))
+  page("forgeqe-runs.md", "Suite and monitor history", runsPage(has))
+  page("forgeqe-readiness.md", "Release readiness history", readinessPage(has))
+  page("forgeqe-external.md", "External datasets", externalPage(has))
+  for (const dataset of bi.datasets) page(`forgeqe-dataset-${dataset.id}.md`, dataset.title, datasetPage(dataset, has))
   return files
 }
 
-function homePage(cfg: AppConfig): string {
-  const bi = cfg.bi || defaultBiConfig(cfg)
+function homePage(bi: BiConfig, has: Set<string>): string {
   const datasetLinks = bi.datasets.length
-    ? bi.datasets.map((d) => `- [${d.title}](./forgeqe-dataset-${d.id})`).join("\n")
+    ? bi.datasets.map((d) => `- [${d.title}](/forgeqe-dataset-${d.id})`).join("\n")
     : "- No external datasets are configured yet. Add them under `bi.datasets` in `forgeqe.yaml`."
   return [
-    "# ForgeQE BI",
-    "",
-    "This static site is generated by `forgeqe bi build`. ForgeQE exports CSV datasets, Evidence queries them with DuckDB, and the build writes static HTML with no always-on backend.",
+    "Generated by `forgeqe bi build` from ForgeQE's suite, monitor and release-readiness reports.",
     "",
     "## Pages",
     "",
-    "- [Suite and monitor history](./forgeqe-runs)",
-    "- [Release readiness history](./forgeqe-readiness)",
-    "- [External datasets](./forgeqe-external)",
+    "- [Suite and monitor history](/forgeqe-runs)",
+    "- [Release readiness history](/forgeqe-readiness)",
+    "- [External datasets](/forgeqe-external)",
     datasetLinks,
     "",
-    sqlBlock(
-      "suite_summary",
+    query(has, "suite_summary",
       `select
   count(*) as suites,
   coalesce(sum(total_cases), 0) as total_cases,
   coalesce(sum(passed_cases), 0) as passed_cases,
   coalesce(sum(failed_cases), 0) as failed_cases,
   coalesce(sum(error_cases), 0) as error_cases
-from forgeqe.suites`,
-    ),
-    "",
-    "{% table data=\"suite_summary\" /%}",
+from ${SOURCE}.suites`),
     "",
     "## Case results by source",
     "",
-    sqlBlock(
-      "cases_by_source",
+    query(has, "cases_by_source",
       `select
   case_source,
   count(*) as total_results,
   sum(case when case_status = 'passed' then 1 else 0 end) as passed_results,
   sum(case when case_status = 'failed' then 1 else 0 end) as failed_results,
   sum(case when case_status = 'error' then 1 else 0 end) as error_results
-from forgeqe.case_results
+from ${SOURCE}.case_results
 group by 1
-order by total_results desc, case_source`,
-    ),
-    "",
-    "{% table data=\"cases_by_source\" /%}",
-    "",
-    "## External datasets",
-    "",
-    sqlBlock(
-      "external_datasets_home",
-      `select dataset_id, title, source_kind, row_count, refreshed_at, page
-from forgeqe.external_datasets
-order by title`,
-    ),
-    "",
-    "{% table data=\"external_datasets_home\" /%}",
+order by total_results desc, case_source`),
     "",
   ].join("\n")
 }
 
-function runsPage(): string {
+function runsPage(has: Set<string>): string {
   return [
-    "# Suite and Monitor History",
-    "",
-    sqlBlock(
-      "suite_timeline",
-      `select
-  started_at,
-  suite_scope,
-  suite_name,
-  total_cases,
-  passed_cases,
-  failed_cases,
-  error_cases,
-  stopped_cases,
-  duration_ms
-from forgeqe.suites
-order by started_at desc`,
-    ),
-    "",
-    "{% table data=\"suite_timeline\" /%}",
+    query(has, "suite_timeline",
+      `select started_at, suite_scope, suite_name, total_cases, passed_cases, failed_cases, error_cases, stopped_cases, duration_ms
+from ${SOURCE}.suites
+order by started_at desc`),
     "",
     "## Slowest case results",
     "",
-    sqlBlock(
-      "slowest_cases",
-      `select
-  suite_id,
-  case_id,
-  case_title,
-  case_source,
-  case_status,
-  duration_ms,
-  tokens
-from forgeqe.case_results
+    query(has, "slowest_cases",
+      `select suite_id, case_id, case_title, case_source, case_status, duration_ms, tokens
+from ${SOURCE}.case_results
 order by duration_ms desc
-limit 50`,
-    ),
-    "",
-    "{% table data=\"slowest_cases\" /%}",
+limit 50`),
     "",
   ].join("\n")
 }
 
-function readinessPage(): string {
+function readinessPage(has: Set<string>): string {
   return [
-    "# Release Readiness History",
-    "",
-    sqlBlock(
-      "readiness_summary",
-      `select
-  report_id,
-  scope,
-  verdict,
-  pass_rate,
-  stories,
-  cases,
-  open_bugs,
-  blockers,
-  risks
-from forgeqe.readiness
-order by report_id desc`,
-    ),
+    query(has, "readiness_summary",
+      `select report_id, scope, verdict, pass_rate, stories, cases, open_bugs, blockers, risks
+from ${SOURCE}.readiness
+order by report_id desc`),
     "",
-    "{% table data=\"readiness_summary\" /%}",
+    "## Stories in the readiness reports",
     "",
-    "## Stories in the latest readiness reports",
-    "",
-    sqlBlock(
-      "readiness_story_table",
-      `select
-  report_id,
-  story_id,
-  story_type,
-  story_title,
-  state,
-  area,
-  case_count
-from forgeqe.readiness_stories
-order by report_id desc, story_id`,
-    ),
-    "",
-    "{% table data=\"readiness_story_table\" /%}",
+    query(has, "readiness_story_table",
+      `select report_id, story_id, story_type, story_title, state, area, case_count
+from ${SOURCE}.readiness_stories
+order by report_id desc, story_id`),
     "",
   ].join("\n")
 }
 
-function externalPage(): string {
+function externalPage(has: Set<string>): string {
   return [
-    "# External Datasets",
-    "",
     "ForgeQE refreshes these datasets from Azure DevOps or Jira during `forgeqe bi sync` and `forgeqe bi build`.",
     "",
-    sqlBlock(
-      "external_datasets_table",
-      `select dataset_id, title, source_kind, row_count, refreshed_at, page
-from forgeqe.external_datasets
-order by title`,
-    ),
-    "",
-    "{% table data=\"external_datasets_table\" /%}",
+    query(has, "external_datasets_table",
+      `select dataset_id, title, source_kind, row_count, refreshed_at
+from ${SOURCE}.external_datasets
+order by title`),
     "",
   ].join("\n")
 }
 
-function datasetPage(dataset: BiDatasetConfig): string {
+function datasetPage(dataset: BiDatasetConfig, has: Set<string>): string {
   return [
-    `# ${dataset.title}`,
-    "",
     `Source kind: \`${dataset.kind}\``,
     "",
-    sqlBlock("dataset_stats", `select count(*) as rows from forgeqe.${dataset.id}`),
-    "",
-    "{% table data=\"dataset_stats\" /%}",
-    "",
-    sqlBlock("dataset_preview", `select * from forgeqe.${dataset.id} limit 100`),
-    "",
-    "{% table data=\"dataset_preview\" /%}",
+    query(has, "dataset_rows", `select * from ${SOURCE}.${dataset.id}`),
     "",
   ].join("\n")
 }
@@ -618,25 +626,20 @@ function collectReadiness(cfg: AppConfig): { summary: ReadinessRow[]; stories: R
   return out
 }
 
-async function exportExternalDatasets(cfg: AppConfig, paths: Paths): Promise<ExternalExport[]> {
+async function exportExternalDatasets(cfg: AppConfig, notes: string[]): Promise<ExternalExport[]> {
   const bi = cfg.bi || defaultBiConfig(cfg)
   const exports: ExternalExport[] = []
   for (const dataset of bi.datasets) {
-    if (dataset.kind === "ado_wiql") {
-      const rows = await fetchAdoRows(cfg, dataset)
-      const file = path.join(paths.externalDataDir, `${dataset.id}.csv`)
-      exports.push({
-        row: { dataset_id: dataset.id, title: dataset.title, source_kind: dataset.kind, row_count: rows.length, refreshed_at: new Date().toISOString(), page: `forgeqe-dataset-${dataset.id}` },
-        files: [writeCsv(file, ADO_DATASET_HEADERS, rows)],
-      })
-    } else {
-      const rows = await fetchJiraRows(cfg, dataset)
-      const file = path.join(paths.externalDataDir, `${dataset.id}.csv`)
-      exports.push({
-        row: { dataset_id: dataset.id, title: dataset.title, source_kind: dataset.kind, row_count: rows.length, refreshed_at: new Date().toISOString(), page: `forgeqe-dataset-${dataset.id}` },
-        files: [writeCsv(file, JIRA_DATASET_HEADERS, rows)],
-      })
+    const headers = dataset.kind === "ado_wiql" ? ADO_DATASET_HEADERS : JIRA_DATASET_HEADERS
+    const rows: Record<string, unknown>[] = dataset.kind === "ado_wiql" ? await fetchAdoRows(cfg, dataset) : await fetchJiraRows(cfg, dataset)
+    if (dataset.kind === "ado_wiql" && rows.length >= ADO_WIQL_MAX) {
+      notes.push(`bi.datasets.${dataset.id}: Azure DevOps returns at most ${ADO_WIQL_MAX} work items per query, so this dataset is probably incomplete; narrow its WIQL.`)
     }
+    exports.push({
+      row: { dataset_id: dataset.id, title: dataset.title, source_kind: dataset.kind, row_count: rows.length, refreshed_at: new Date().toISOString(), page: `forgeqe-dataset-${dataset.id}` },
+      headers,
+      rows,
+    })
   }
   return exports
 }
@@ -644,71 +647,57 @@ async function exportExternalDatasets(cfg: AppConfig, paths: Paths): Promise<Ext
 async function fetchAdoRows(cfg: AppConfig, dataset: Extract<BiDatasetConfig, { kind: "ado_wiql" }>): Promise<Record<string, string | number>[]> {
   const { auth, org, project: configured } = adoSettings(cfg.sources)
   const project = dataset.project || configured
-  return cachedJson(cfg.cache, {
-    namespace: "bi:ado_wiql",
-    keyParts: [org, project || "", dataset.wiql],
-    ttlSeconds: cfg.cache?.biTtlSeconds,
-    load: async () => {
-      const base = project ? `${org}/${encodeURIComponent(project)}` : org
-      const { data } = await http<{ workItems?: { id: number }[]; workItemRelations?: { source?: { id?: number } | null; target?: { id?: number } | null }[] }>(
-        `${base}/_apis/wit/wiql?api-version=7.1&$top=500`,
-        { auth, body: { query: dataset.wiql } },
-      )
-      const ids = [...new Set([...(data.workItems || []).map((w) => w.id), ...(data.workItemRelations || []).flatMap((r) => [r.source?.id, r.target?.id]).filter((id): id is number => typeof id === "number")])].slice(0, 500)
-      if (!ids.length) return []
-      const fields = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.AssignedTo", "System.ChangedDate", "System.IterationPath", "System.TeamProject"]
-      const rows: Record<string, string | number>[] = []
-      for (let i = 0; i < ids.length; i += 200) {
-        const batch = await http<{ value?: { id: number; fields: Record<string, unknown> }[] }>(`${org}/_apis/wit/workitemsbatch?api-version=7.1`, { auth, body: { ids: ids.slice(i, i + 200), fields } })
-        for (const item of batch.data.value || []) {
-          rows.push({
-            id: item.id,
-            project: String(item.fields["System.TeamProject"] || project || ""),
-            type: String(item.fields["System.WorkItemType"] || ""),
-            title: String(item.fields["System.Title"] || ""),
-            state: String(item.fields["System.State"] || ""),
-            assigned_to: displayName(item.fields["System.AssignedTo"]),
-            changed_at: String(item.fields["System.ChangedDate"] || ""),
-            iteration: String(item.fields["System.IterationPath"] || ""),
-          })
-        }
-      }
-      return rows
-    },
-  })
+  const base = project ? `${org}/${encodeURIComponent(project)}` : org
+  const { data } = await http<{ workItems?: { id: number }[]; workItemRelations?: { source?: { id?: number } | null; target?: { id?: number } | null }[] }>(
+    `${base}/_apis/wit/wiql?api-version=7.1&$top=${ADO_WIQL_MAX}`,
+    { auth, body: { query: dataset.wiql } },
+  )
+  const ids = [...new Set([...(data.workItems || []).map((w) => w.id), ...(data.workItemRelations || []).flatMap((r) => [r.source?.id, r.target?.id]).filter((id): id is number => typeof id === "number")])]
+  if (!ids.length) return []
+  const fields = ["System.Id", "System.WorkItemType", "System.Title", "System.State", "System.AssignedTo", "System.ChangedDate", "System.IterationPath", "System.TeamProject"]
+  const rows: Record<string, string | number>[] = []
+  for (let i = 0; i < ids.length; i += 200) {
+    const batch = await http<{ value?: { id: number; fields: Record<string, unknown> }[] }>(`${org}/_apis/wit/workitemsbatch?api-version=7.1`, { auth, body: { ids: ids.slice(i, i + 200), fields } })
+    for (const item of batch.data.value || []) {
+      rows.push({
+        id: item.id,
+        project: String(item.fields["System.TeamProject"] || project || ""),
+        type: String(item.fields["System.WorkItemType"] || ""),
+        title: String(item.fields["System.Title"] || ""),
+        state: String(item.fields["System.State"] || ""),
+        assigned_to: displayName(item.fields["System.AssignedTo"]),
+        changed_at: String(item.fields["System.ChangedDate"] || ""),
+        iteration: String(item.fields["System.IterationPath"] || ""),
+      })
+    }
+  }
+  return rows
 }
 
 async function fetchJiraRows(cfg: AppConfig, dataset: Extract<BiDatasetConfig, { kind: "jira_jql" }>): Promise<Record<string, string>[]> {
   const jira = jiraApi(cfg.sources)
   const fields = "summary,status,statuscategory,issuetype,priority,assignee,reporter,labels,components,parent,created,updated"
-  return cachedJson(cfg.cache, {
-    namespace: "bi:jira_jql",
-    keyParts: [jira.url, jira.cloud, dataset.jql, fields],
-    ttlSeconds: cfg.cache?.biTtlSeconds,
-    load: async () => {
-      const rows: Record<string, string>[] = []
-      if (jira.cloud) {
-        let next: string | undefined
-        do {
-          const q = new URLSearchParams({ jql: dataset.jql, fields, maxResults: "100", ...(next ? { nextPageToken: next } : {}) })
-          const { data } = await http<{ issues?: any[]; nextPageToken?: string; isLast?: boolean }>(`${jira.api}/search/jql?${q}`, { auth: jira.auth })
-          for (const issue of data.issues || []) rows.push(jiraRow(jira.url, issue))
-          next = data.isLast === false || data.nextPageToken ? data.nextPageToken : undefined
-        } while (next)
-      } else {
-        let startAt = 0
-        for (;;) {
-          const q = new URLSearchParams({ jql: dataset.jql, fields, maxResults: "100", startAt: String(startAt) })
-          const { data } = await http<{ issues?: any[]; total?: number }>(`${jira.api}/search?${q}`, { auth: jira.auth })
-          const page = data.issues || []
-          for (const issue of page) rows.push(jiraRow(jira.url, issue))
-          startAt += page.length
-          if (!page.length || startAt >= Number(data.total || 0)) break
-        }
-      }
-      return rows
-    },
-  })
+  const rows: Record<string, string>[] = []
+  if (jira.cloud) {
+    let next: string | undefined
+    do {
+      const q = new URLSearchParams({ jql: dataset.jql, fields, maxResults: "100", ...(next ? { nextPageToken: next } : {}) })
+      const { data } = await http<{ issues?: any[]; nextPageToken?: string; isLast?: boolean }>(`${jira.api}/search/jql?${q}`, { auth: jira.auth })
+      for (const issue of data.issues || []) rows.push(jiraRow(jira.url, issue))
+      next = data.isLast === false || data.nextPageToken ? data.nextPageToken : undefined
+    } while (next)
+  } else {
+    let startAt = 0
+    for (;;) {
+      const q = new URLSearchParams({ jql: dataset.jql, fields, maxResults: "100", startAt: String(startAt) })
+      const { data } = await http<{ issues?: any[]; total?: number }>(`${jira.api}/search?${q}`, { auth: jira.auth })
+      const page = data.issues || []
+      for (const issue of page) rows.push(jiraRow(jira.url, issue))
+      startAt += page.length
+      if (!page.length || startAt >= Number(data.total || 0)) break
+    }
+  }
+  return rows
 }
 
 function jiraRow(baseUrl: string, issue: Record<string, any>): Record<string, string> {
@@ -779,22 +768,18 @@ function readJson<T>(file: string): T | null {
   }
 }
 
-function sqlPath(file: string): string {
-  return file.split(path.sep).join("/").replace(/'/g, "''")
-}
-
 function sqlBlock(name: string, sql: string): string {
   return `\`\`\`sql ${name}\n${sql}\n\`\`\``
 }
 
-function summaryMarkdown(
-  cfg: AppConfig,
-  paths: Paths,
-  suites: { suites: SuiteRow[]; cases: CaseRow[]; steps: StepRow[]; writebacks: WriteBackRow[] },
-  readiness: { summary: ReadinessRow[] },
-  external: ExternalExport[],
-): string {
-  const bi = cfg.bi || defaultBiConfig(cfg)
+/** A query and its table on an Evidence page, or "None yet." while the table it reads has no rows. */
+function query(has: Set<string>, name: string, sql: string): string {
+  const table = sql.match(new RegExp(`from ${SOURCE}\\.(\\w+)`))?.[1]
+  if (table && !has.has(table)) return "None yet."
+  return `${sqlBlock(name, sql)}\n\n<DataTable data={${name}} rows=25/>`
+}
+
+function summaryMarkdown(bi: BiConfig, paths: Paths, suites: SuiteData, readiness: ReadinessData, external: ExternalExport[]): string {
   return [
     `# ${bi.title}`,
     "",
@@ -808,27 +793,122 @@ function summaryMarkdown(
     `- Release readiness reports exported: ${readiness.summary.length}`,
     `- External datasets exported: ${external.length}`,
     "",
-    external.length ? "## External datasets" : "## External datasets",
+    "## External datasets",
     "",
     ...(external.length ? external.map((d) => `- ${d.row.title} (\`${d.row.dataset_id}\`): ${d.row.row_count} row${d.row.row_count === 1 ? "" : "s"}`) : ["- None configured. Add datasets under `bi.datasets` in `forgeqe.yaml`."]),
     "",
   ].join("\n")
 }
 
-async function runEvidence(args: string[], cwd: string, extraEnv: Record<string, string> = {}): Promise<void> {
-  const evidence = Bun.which("evidence")
-  const command = evidence ? evidence : Bun.which("npx")
-  if (!command) throw new Error("Evidence CLI not found and npx is unavailable. Install Node.js or the Evidence CLI first.")
-  const fullArgs = evidence ? args : ["-p", "evidence", "evidence", ...args]
+/** ForgeQE's own page from the same data, through the shared report page (reportHtml): no Node, no server. */
+function staticReport(bi: BiConfig, paths: Paths, suites: SuiteData, readiness: ReadinessData, external: ExternalExport[], reason: string): string {
+  const passed = suites.cases.filter((c) => c.case_status === "passed").length
+  const failed = suites.cases.filter((c) => c.case_status === "failed").length
+  const errors = suites.cases.filter((c) => c.case_status === "error").length
+  const bySource = new Map<string, { total: number; passed: number; failed: number; errors: number }>()
+  for (const c of suites.cases) {
+    const s = bySource.get(c.case_source) || { total: 0, passed: 0, failed: 0, errors: 0 }
+    s.total++
+    if (c.case_status === "passed") s.passed++
+    if (c.case_status === "failed") s.failed++
+    if (c.case_status === "error") s.errors++
+    bySource.set(c.case_source, s)
+  }
+  const newestFirst = [...suites.suites].reverse().slice(0, 100)
+  const slowest = [...suites.cases].sort((a, b) => b.duration_ms - a.duration_ms).slice(0, 50)
+  const markdown = [
+    `Built by ForgeQE without Evidence (${reason}). The CSV datasets are in \`${paths.dataDir}\`.`,
+    "",
+    "## Summary",
+    "",
+    `- Suite runs: ${suites.suites.length}`,
+    `- Case results: ${suites.cases.length} (${passed} passed, ${failed} failed, ${errors} error${errors === 1 ? "" : "s"})`,
+    `- Release readiness reports: ${readiness.summary.length}`,
+    `- External datasets: ${external.length}`,
+    "",
+    "## Case results by source",
+    "",
+    mdTable(
+      ["Source", "Results", "Passed", "Failed", "Errors"],
+      [...bySource].sort((a, b) => b[1].total - a[1].total).map(([source, s]) => [source, s.total, s.passed, s.failed, s.errors]),
+    ),
+    "",
+    "## Suite and monitor history",
+    "",
+    mdTable(
+      ["Started", "Scope", "Suite", "Cases", "Passed", "Failed", "Errors", "Stopped", "Duration"],
+      newestFirst.map((s) => [s.started_at, s.suite_scope, s.suite_name, s.total_cases, s.passed_cases, s.failed_cases, s.error_cases, s.stopped_cases, duration(s.duration_ms)]),
+    ),
+    "",
+    "## Slowest case results",
+    "",
+    mdTable(
+      ["Suite", "Case", "Title", "Source", "Status", "Duration", "Tokens"],
+      slowest.map((c) => [c.suite_id, c.case_id, c.case_title, c.case_source, c.case_status, duration(c.duration_ms), c.tokens]),
+    ),
+    "",
+    "## Release readiness",
+    "",
+    mdTable(
+      ["Report", "Scope", "Verdict", "Pass rate", "Stories", "Cases", "Open bugs", "Blockers"],
+      [...readiness.summary].reverse().map((r) => [r.report_id, r.scope, r.verdict, r.pass_rate === "" ? "" : `${r.pass_rate}%`, r.stories, r.cases, r.open_bugs, r.blockers]),
+    ),
+    "",
+    "## External datasets",
+    "",
+    ...(external.length
+      ? external.flatMap((d) => [
+          `### ${d.row.title}`,
+          "",
+          `\`${d.row.dataset_id}\` · ${d.row.source_kind} · ${d.row.row_count} row${d.row.row_count === 1 ? "" : "s"}${d.rows.length > 100 ? ", first 100 shown" : ""}`,
+          "",
+          mdTable(d.headers, d.rows.slice(0, 100).map((row) => d.headers.map((h) => row[h]))),
+          "",
+        ])
+      : ["None configured. Add datasets under `bi.datasets` in `forgeqe.yaml`.", ""]),
+  ].join("\n")
+  return reportHtml(bi.title, markdown, new Date())
+}
+
+function mdTable(headers: readonly string[], rows: unknown[][]): string {
+  if (!rows.length) return "None yet."
+  const cell = (v: unknown) => (v === undefined || v === null ? "" : String(v)).replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ")
+  return [`| ${headers.map(cell).join(" | ")} |`, `| ${headers.map(() => "---").join(" | ")} |`, ...rows.map((r) => `| ${r.map(cell).join(" | ")} |`)].join("\n")
+}
+
+function errorText(err: unknown): string {
+  return err instanceof Error ? err.message : String(err)
+}
+
+/** npm install in the Evidence project, once: skipped while its packages are there. */
+async function installEvidence(paths: Paths): Promise<void> {
+  if (existsSync(path.join(paths.evidenceDir, "node_modules", "@evidence-dev", "evidence", "package.json"))) return
+  await run("npm", ["install", "--no-audit", "--no-fund"], paths.evidenceDir)
+}
+
+/** evidence sources (CSV → the site's data), then evidence build:strict, then the site copied to the build directory. */
+async function buildWithEvidence(paths: Paths): Promise<void> {
+  await installEvidence(paths)
+  await run("npx", ["--no-install", "evidence", "sources"], paths.evidenceDir)
+  await run("npx", ["--no-install", "evidence", "build:strict"], paths.evidenceDir)
+  const site = path.join(paths.evidenceDir, "build")
+  if (!existsSync(path.join(site, "index.html"))) throw new Error(`Evidence finished without writing ${path.join(site, "index.html")}`)
+  if (path.resolve(site) !== path.resolve(paths.buildDir)) cpSync(site, paths.buildDir, { recursive: true, force: true })
+}
+
+async function run(command: string, args: string[], cwd: string): Promise<void> {
+  if (runnerOverride) return runnerOverride(command, args, cwd)
+  const bin = Bun.which(command)
+  if (!bin) throw new Error(`${command} not found; install Node.js 18 or later to build the Evidence site`)
   await new Promise<void>((resolve, reject) => {
-    const child = spawn(command, fullArgs, {
+    const child = spawn(bin, args, {
       cwd,
       stdio: "inherit",
       shell: process.platform === "win32",
-      env: { ...process.env, DO_NOT_TRACK: "1", EVIDENCE_TELEMETRY_DISABLED: "1", ...extraEnv },
+      env: { ...process.env, DO_NOT_TRACK: "1", EVIDENCE_TELEMETRY_DISABLED: "1" },
     })
     child.on("error", reject)
-    child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`Evidence command failed (${[command, ...fullArgs].join(" ")}).`))))
+    child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`${[command, ...args].join(" ")} exited with code ${code}`))))
   })
 }