@capagents/forgeqe 1.1.1 → 1.1.3

package/src/bi.ts

@@ -0,0 +1,914 @@
+import { spawn } from "node:child_process"
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import path from "node:path"
+
+import type { Readiness } from "./cases/readiness.ts"
+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 { counts as suiteCounts } from "./suite/report.ts"
+
+type BuildOverrides = { evidenceDir?: string; dataDir?: string; buildDir?: string }
+type Paths = {
+  evidenceDir: string
+  dataDir: string
+  buildDir: string
+  sourceDir: string
+  pagesDir: string
+  externalDataDir: string
+}
+
+type SuiteFile = {
+  name?: string
+  startedAt?: string
+  ms?: number
+  stopped?: boolean
+  results?: CaseResult[]
+  writeBack?: WriteBack[]
+}
+
+type SuiteRow = {
+  suite_id: string
+  suite_scope: "suite" | "monitor"
+  suite_name: string
+  started_at: string
+  duration_ms: number
+  total_cases: number
+  passed_cases: number
+  failed_cases: number
+  error_cases: number
+  stopped_cases: number
+  coded_cases: number
+  coded_passed_cases: number
+}
+
+type CaseRow = {
+  suite_id: string
+  suite_scope: "suite" | "monitor"
+  case_id: string
+  case_title: string
+  case_source: string
+  case_status: string
+  started_at: string
+  finished_at: string
+  duration_ms: number
+  tokens: number
+  final_url: string
+  run_dir: string
+  group: string
+  tags: string
+  requirements: string
+  failure_type: string
+  failure_action: string
+  bug_label: string
+  bug_url: string
+  code_status: string
+  code_test_file: string
+  code_command: string
+}
+
+type StepRow = {
+  suite_id: string
+  suite_scope: "suite" | "monitor"
+  case_id: string
+  step_number: number
+  action: string
+  data: string
+  expected: string
+  status: string
+  actual: string
+  cause: string
+}
+
+type WriteBackRow = {
+  suite_id: string
+  suite_scope: "suite" | "monitor"
+  case_id: string
+  source: string
+  text: string
+  url: string
+  error: string
+}
+
+type ReadinessRow = {
+  report_id: string
+  scope: string
+  verdict: string
+  pass_rate: number | ""
+  stories: number
+  untested_stories: number
+  cases: number
+  automated_cases: number
+  executed_cases: number
+  passed_cases: number
+  failed_cases: number
+  blocked_cases: number
+  not_run_cases: number
+  flaky_cases: number
+  quarantined_cases: number
+  open_bugs: number
+  blockers: string
+  risks: string
+  notes: string
+}
+
+type ReadinessStoryRow = {
+  report_id: string
+  story_id: number
+  story_type: string
+  story_title: string
+  state: string
+  url: string
+  area: string
+  case_count: number
+}
+
+type ReadinessCaseRow = {
+  report_id: string
+  story_id: number
+  case_id: number
+  case_title: string
+  automated: string
+  outcome: string
+  from: string
+  when: string
+  flaky: string
+  quarantined: string
+  url: string
+}
+
+type ExternalDatasetRow = {
+  dataset_id: string
+  title: string
+  source_kind: string
+  row_count: number
+  refreshed_at: string
+  page: string
+}
+
+type ExternalExport = { row: ExternalDatasetRow; files: string[] }
+
+export type BiSyncResult = {
+  evidenceDir: string
+  dataDir: string
+  buildDir: string
+  suites: number
+  caseResults: number
+  readinessReports: number
+  externalDatasets: number
+  dataFiles: string[]
+  pageFiles: string[]
+  summaryFile: string
+}
+
+export type BiBuildResult = BiSyncResult & { indexFile: string }
+
+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 async function syncBiData(cfg: AppConfig, overrides: BuildOverrides = {}): Promise<BiSyncResult> {
+  const bi = cfg.bi || defaultBiConfig(cfg)
+  const paths = resolvePaths(bi, overrides)
+  await ensureEvidenceProject(paths.evidenceDir)
+  const pageFiles = writeManagedEvidenceFiles({ ...cfg, bi }, paths)
+
+  mkdirSync(paths.dataDir, { recursive: true })
+  mkdirSync(paths.buildDir, { recursive: true })
+  mkdirSync(paths.externalDataDir, { 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 summaryFile = path.join(paths.buildDir, "summary.md")
+  writeFileSync(summaryFile, summaryMarkdown({ ...cfg, 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,
+  }
+}
+
+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") }
+}
+
+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)
+  return {
+    evidenceDir,
+    dataDir,
+    buildDir,
+    sourceDir: path.join(evidenceDir, "sources", "forgeqe"),
+    pagesDir: path.join(evidenceDir, "pages"),
+    externalDataDir: path.join(dataDir, "external"),
+  }
+}
+
+function defaultBiConfig(cfg: AppConfig): BiConfig {
+  const evidenceDir = path.resolve("evidence")
+  return {
+    title: "ForgeQE BI",
+    evidenceDir,
+    dataDir: path.join(evidenceDir, "sources", "forgeqe", "data"),
+    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())
+}
+
+function writeManagedEvidenceFiles(cfg: AppConfig, paths: Paths): string[] {
+  const bi = cfg.bi || defaultBiConfig(cfg)
+  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)))
+  }
+  return files
+}
+
+function homePage(cfg: AppConfig): string {
+  const bi = cfg.bi || defaultBiConfig(cfg)
+  const datasetLinks = bi.datasets.length
+    ? 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.",
+    "",
+    "## Pages",
+    "",
+    "- [Suite and monitor history](./forgeqe-runs)",
+    "- [Release readiness history](./forgeqe-readiness)",
+    "- [External datasets](./forgeqe-external)",
+    datasetLinks,
+    "",
+    sqlBlock(
+      "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\" /%}",
+    "",
+    "## Case results by source",
+    "",
+    sqlBlock(
+      "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
+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\" /%}",
+    "",
+  ].join("\n")
+}
+
+function runsPage(): 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\" /%}",
+    "",
+    "## Slowest case results",
+    "",
+    sqlBlock(
+      "slowest_cases",
+      `select
+  suite_id,
+  case_id,
+  case_title,
+  case_source,
+  case_status,
+  duration_ms,
+  tokens
+from forgeqe.case_results
+order by duration_ms desc
+limit 50`,
+    ),
+    "",
+    "{% table data=\"slowest_cases\" /%}",
+    "",
+  ].join("\n")
+}
+
+function readinessPage(): 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`,
+    ),
+    "",
+    "{% table data=\"readiness_summary\" /%}",
+    "",
+    "## 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\" /%}",
+    "",
+  ].join("\n")
+}
+
+function externalPage(): 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\" /%}",
+    "",
+  ].join("\n")
+}
+
+function datasetPage(dataset: BiDatasetConfig): 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\" /%}",
+    "",
+  ].join("\n")
+}
+
+function collectSuiteData(cfg: AppConfig): { suites: SuiteRow[]; cases: CaseRow[]; steps: StepRow[]; writebacks: WriteBackRow[] } {
+  const suites: SuiteRow[] = []
+  const cases: CaseRow[] = []
+  const steps: StepRow[] = []
+  const writebacks: WriteBackRow[] = []
+  for (const [root, scope] of [
+    [cfg.suite.outDir, "suite" as const],
+    [cfg.monitor.outDir, "monitor" as const],
+  ] as Array<[string, "suite" | "monitor"]>) {
+    for (const dir of suiteDirs(root)) {
+      const suite = readJson<SuiteFile>(path.join(dir, "suite.json"))
+      if (!suite) continue
+      const results = suite.results || []
+      const c = suiteCounts(results)
+      suites.push({
+        suite_id: path.basename(dir),
+        suite_scope: scope,
+        suite_name: suite.name || path.basename(dir),
+        started_at: suite.startedAt || "",
+        duration_ms: Number(suite.ms || 0),
+        total_cases: c.total,
+        passed_cases: c.passed,
+        failed_cases: c.failed,
+        error_cases: c.errors,
+        stopped_cases: c.stopped,
+        coded_cases: c.coded,
+        coded_passed_cases: c.codePassed,
+      })
+      for (const result of results) {
+        cases.push({
+          suite_id: path.basename(dir),
+          suite_scope: scope,
+          case_id: result.case.id,
+          case_title: result.case.title,
+          case_source: result.case.source,
+          case_status: result.status,
+          started_at: result.startedAt || "",
+          finished_at: result.finishedAt || "",
+          duration_ms: Number(result.ms || 0),
+          tokens: Number(result.tokens || 0),
+          final_url: result.finalUrl || "",
+          run_dir: result.runDir || "",
+          group: result.case.group || "",
+          tags: (result.case.tags || []).join("; "),
+          requirements: (result.case.requirements || []).join("; "),
+          failure_type: result.failure?.type || "",
+          failure_action: result.failure ? FAILURE_ACTION[result.failure.type] : "",
+          bug_label: result.bug?.label || "",
+          bug_url: result.bug?.url || "",
+          code_status: result.code?.status || "",
+          code_test_file: result.code?.testFile || "",
+          code_command: result.code?.command || "",
+        })
+        const verdicts = new Map((result.stepResults || []).map((v) => [v.step, v]))
+        result.case.steps.forEach((step, i) => {
+          const verdict = verdicts.get(i + 1)
+          steps.push({
+            suite_id: path.basename(dir),
+            suite_scope: scope,
+            case_id: result.case.id,
+            step_number: i + 1,
+            action: step.action,
+            data: step.data || "",
+            expected: step.expected || "",
+            status: verdict?.status || "",
+            actual: verdict?.actual || "",
+            cause: verdict?.cause || "",
+          })
+        })
+      }
+      for (const post of suite.writeBack || []) {
+        writebacks.push({
+          suite_id: path.basename(dir),
+          suite_scope: scope,
+          case_id: post.caseId || "",
+          source: post.source,
+          text: post.text,
+          url: post.url || "",
+          error: post.error || "",
+        })
+      }
+    }
+  }
+  suites.sort((a, b) => a.started_at.localeCompare(b.started_at))
+  cases.sort((a, b) => a.started_at.localeCompare(b.started_at) || a.case_id.localeCompare(b.case_id))
+  return { suites, cases, steps, writebacks }
+}
+
+function collectReadiness(cfg: AppConfig): { summary: ReadinessRow[]; stories: ReadinessStoryRow[]; cases: ReadinessCaseRow[] } {
+  const out = { summary: [] as ReadinessRow[], stories: [] as ReadinessStoryRow[], cases: [] as ReadinessCaseRow[] }
+  const root = path.join(cfg.export.outDir, "readiness")
+  if (!existsSync(root)) return out
+  for (const name of readdirSync(root).sort()) {
+    const report = readJson<Readiness>(path.join(root, name, "readiness.json"))
+    if (!report?.scope || !report.counts) continue
+    out.summary.push({
+      report_id: name,
+      scope: report.scope,
+      verdict: report.verdict,
+      pass_rate: report.passRate ?? "",
+      stories: report.counts.stories,
+      untested_stories: report.counts.untested,
+      cases: report.counts.cases,
+      automated_cases: report.counts.automated,
+      executed_cases: report.counts.executed,
+      passed_cases: report.counts.passed,
+      failed_cases: report.counts.failed,
+      blocked_cases: report.counts.blocked,
+      not_run_cases: report.counts.notRun,
+      flaky_cases: report.counts.flaky,
+      quarantined_cases: report.counts.quarantined,
+      open_bugs: report.bugs.length,
+      blockers: report.blockers.join(" | "),
+      risks: report.risks.join(" | "),
+      notes: report.notes.join(" | "),
+    })
+    for (const story of report.stories) {
+      out.stories.push({
+        report_id: name,
+        story_id: story.id,
+        story_type: story.type,
+        story_title: story.title,
+        state: story.state,
+        url: story.url,
+        area: story.area || "",
+        case_count: story.cases.length,
+      })
+      for (const tc of story.cases) {
+        out.cases.push({
+          report_id: name,
+          story_id: story.id,
+          case_id: tc.id,
+          case_title: tc.title,
+          automated: tc.automated ? "yes" : "no",
+          outcome: tc.outcome,
+          from: tc.from || "",
+          when: tc.when || "",
+          flaky: tc.flaky ? "yes" : "no",
+          quarantined: tc.quarantined ? "yes" : "no",
+          url: tc.url,
+        })
+      }
+    }
+  }
+  return out
+}
+
+async function exportExternalDatasets(cfg: AppConfig, paths: Paths): 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)],
+      })
+    }
+  }
+  return exports
+}
+
+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
+    },
+  })
+}
+
+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
+    },
+  })
+}
+
+function jiraRow(baseUrl: string, issue: Record<string, any>): Record<string, string> {
+  const fields = (issue.fields || {}) as Record<string, any>
+  return {
+    key: String(issue.key || ""),
+    summary: String(fields.summary || ""),
+    status: String(fields.status?.name || ""),
+    status_category: String(fields.status?.statusCategory?.name || fields.statuscategory?.name || ""),
+    issue_type: String(fields.issuetype?.name || ""),
+    priority: String(fields.priority?.name || ""),
+    assignee: displayName(fields.assignee),
+    reporter: displayName(fields.reporter),
+    parent_key: String(fields.parent?.key || ""),
+    parent_summary: String(fields.parent?.fields?.summary || ""),
+    labels: (Array.isArray(fields.labels) ? fields.labels : []).join("; "),
+    components: (Array.isArray(fields.components) ? fields.components.map((c: { name?: string }) => c.name).filter(Boolean) : []).join("; "),
+    created_at: String(fields.created || ""),
+    updated_at: String(fields.updated || ""),
+    url: issue.key ? `${baseUrl}/browse/${issue.key}` : "",
+  }
+}
+
+function displayName(value: unknown): string {
+  return value && typeof value === "object" ? String((value as { displayName?: string; name?: string }).displayName || (value as { name?: string }).name || "") : String(value || "")
+}
+
+function suiteDirs(root: string): string[] {
+  if (!existsSync(root)) return []
+  return readdirSync(root)
+    .map((name) => path.join(root, name))
+    .filter((dir) => existsSync(path.join(dir, "suite.json")))
+}
+
+function writeText(file: string, body: string): string {
+  mkdirSync(path.dirname(file), { recursive: true })
+  writeFileSync(file, body, "utf8")
+  return file
+}
+
+function writeCsv(file: string, headers: readonly string[], rows: Record<string, unknown>[]): string {
+  mkdirSync(path.dirname(file), { recursive: true })
+  const lines = [headers.join(","), ...rows.map((row) => headers.map((h) => csvCell(row[h])).join(","))]
+  writeFileSync(file, `${lines.join("\n")}\n`, "utf8")
+  return file
+}
+
+function csvCell(value: unknown): string {
+  const text =
+    value === undefined || value === null
+      ? ""
+      : typeof value === "string"
+        ? value
+        : typeof value === "number" || typeof value === "boolean"
+          ? String(value)
+          : Array.isArray(value)
+            ? value.join("; ")
+            : JSON.stringify(value)
+  return /[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text
+}
+
+function readJson<T>(file: string): T | null {
+  if (!existsSync(file)) return null
+  try {
+    return JSON.parse(readFileSync(file, "utf8")) as T
+  } catch {
+    return 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)
+  return [
+    `# ${bi.title}`,
+    "",
+    `Generated at ${new Date().toISOString()}.`,
+    "",
+    `- Evidence project: \`${paths.evidenceDir}\``,
+    `- Static build: \`${paths.buildDir}\``,
+    `- Data export: \`${paths.dataDir}\``,
+    `- Suite runs exported: ${suites.suites.length}`,
+    `- Case results exported: ${suites.cases.length}`,
+    `- Release readiness reports exported: ${readiness.summary.length}`,
+    `- External datasets exported: ${external.length}`,
+    "",
+    external.length ? "## 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]
+  await new Promise<void>((resolve, reject) => {
+    const child = spawn(command, fullArgs, {
+      cwd,
+      stdio: "inherit",
+      shell: process.platform === "win32",
+      env: { ...process.env, DO_NOT_TRACK: "1", EVIDENCE_TELEMETRY_DISABLED: "1", ...extraEnv },
+    })
+    child.on("error", reject)
+    child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`Evidence command failed (${[command, ...fullArgs].join(" ")}).`))))
+  })
+}
+
+const SUITE_HEADERS = [
+  "suite_id",
+  "suite_scope",
+  "suite_name",
+  "started_at",
+  "duration_ms",
+  "total_cases",
+  "passed_cases",
+  "failed_cases",
+  "error_cases",
+  "stopped_cases",
+  "coded_cases",
+  "coded_passed_cases",
+] as const
+
+const CASE_HEADERS = [
+  "suite_id",
+  "suite_scope",
+  "case_id",
+  "case_title",
+  "case_source",
+  "case_status",
+  "started_at",
+  "finished_at",
+  "duration_ms",
+  "tokens",
+  "final_url",
+  "run_dir",
+  "group",
+  "tags",
+  "requirements",
+  "failure_type",
+  "failure_action",
+  "bug_label",
+  "bug_url",
+  "code_status",
+  "code_test_file",
+  "code_command",
+] as const
+
+const STEP_HEADERS = [
+  "suite_id",
+  "suite_scope",
+  "case_id",
+  "step_number",
+  "action",
+  "data",
+  "expected",
+  "status",
+  "actual",
+  "cause",
+] as const
+
+const WRITEBACK_HEADERS = ["suite_id", "suite_scope", "case_id", "source", "text", "url", "error"] as const
+const READINESS_HEADERS = [
+  "report_id",
+  "scope",
+  "verdict",
+  "pass_rate",
+  "stories",
+  "untested_stories",
+  "cases",
+  "automated_cases",
+  "executed_cases",
+  "passed_cases",
+  "failed_cases",
+  "blocked_cases",
+  "not_run_cases",
+  "flaky_cases",
+  "quarantined_cases",
+  "open_bugs",
+  "blockers",
+  "risks",
+  "notes",
+] as const
+const READINESS_STORY_HEADERS = ["report_id", "story_id", "story_type", "story_title", "state", "url", "area", "case_count"] as const
+const READINESS_CASE_HEADERS = ["report_id", "story_id", "case_id", "case_title", "automated", "outcome", "from", "when", "flaky", "quarantined", "url"] as const
+const EXTERNAL_HEADERS = ["dataset_id", "title", "source_kind", "row_count", "refreshed_at", "page"] as const
+const ADO_DATASET_HEADERS = ["id", "project", "type", "title", "state", "assigned_to", "changed_at", "iteration"] as const
+const JIRA_DATASET_HEADERS = ["key", "summary", "status", "status_category", "issue_type", "priority", "assignee", "reporter", "parent_key", "parent_summary", "labels", "components", "created_at", "updated_at", "url"] as const