// A static markdown rendering of an evaluated UI for clients that cannot run // it (mobile app, notifications, CLI): readable on a phone, no HTML. import type { LoadedData } from "./data"; import { acceptanceVerdict, cellsLine, checkLabel, isCellGap, isGap, needsPlaces, ownerContradiction, readAcceptance, type Check, type Evidence as AcceptanceEvidence } from "./acceptance"; import { conditionDifferences, conditionsWarning, readCompare, type CompareImage } from "./compare"; import { analyse, countsText, describeRegion, formatClock, formatWer, readTracks } from "./transcript"; import { formatConditions, formatRatio, groupRuns, readBenchmark, runStatusWord, unmeasuredCounts, type AllRunsReport, type Comparison, type Context, type Run, } from "./benchmark"; import { formatAmount as perfAmount, formatBytes, formatDelta, formatMs, formatPercent as formatChange, formatShare } from "./perf-units"; import { readTreemap, type TreeNode } from "./treemap"; import { readWaterfall, type Span } from "./waterfall"; import { coverageTone, formatPercent, headline, mostUncovered, percent, rangeLabel, readCoverage } from "./coverage"; import { countSeverities, readFindings, SEVERITIES, severityCount, severityLabel, sortFindings, statusCounts, statusSentence, verdictHeadline, type Severity, } from "./findings"; import { GROUP_LABEL, groupOutdated, readDependencies, SEVERITIES as DEPENDENCY_SEVERITIES, splitChange, type OutdatedPackage, type Severity as DependencySeverity, type VulnerablePackage, } from "./dependencies"; import { formatElapsed, jobCountsText, matrixPrefix, readPipeline, STATUS_LABEL, type PipelineJob, type PipelineStatus } from "./pipeline"; import { evaluate, initialState, isPlainObject } from "./evaluate"; import { compile } from "./index"; import { estimateTask, estimateTotals, estimateUnit, formatAmount, formatQuantity, formatWithUnit, initialChecks, joinAnd, leaderMargin, planTotal, rankOptions, readDecision, readEstimate, readPlan, round, } from "./decisions"; import { ATTENTION_LABEL, CHANGE_LABEL, changeTotals, CHECKS_LABEL, checkCounts, MERGEABILITY_LABEL, parseChangesTarget, parseCommitLimit, parsePathFilter, parseThreadIds, PR_STATE_LABEL, projectRequestKey, relativeTime, REVIEW_LABEL, scopeLabel, threadStatusLabel, type ChangesView, type CommitsView, type Parsed, type ProjectRequest, type ProjectResult, type PullRequestView, type ThreadsView, } from "./project"; import { previewText, threadActivityLabel } from "./thread-activity"; import { commonDirectory, displayPath, formatDuration, readTestRun, stripAnsi } from "./test-results"; import { firstError, foldRepeats, readLogs, LOG_LEVELS } from "./logs"; import { frameRows, memberPlaces, readTrace, relationLabel, type TraceFrame } from "./stack-trace"; import { aheadBehindLabel, defaultEnvironments, environmentTitle, kindLabel, LIFE_LABEL, liveThreads, threadSummary, uncommittedLabel, type EnvironmentInfo, } from "./environments"; import { cardLate, formatDay, formatDays, formatRange, HEALTH_LABEL, healthSummary, itemDays, localDay, readBoard, readRoadmap, readStatus, relativeDue, ROADMAP_STATUS_LABEL, type BoardCard, type Health, type RoadmapStatus, } from "./tracking"; import { chainSummary, readProvenance, RECEIPT_LABEL, shortValue, STAGE_STATUS_LABEL, type Evidence as ProvenanceEvidence, type Fact as ProvenanceFact, } from "./provenance"; import type { UiNode, Value } from "./types"; const TONE_DOTS: Record = { good: "🟒", warn: "🟠", bad: "πŸ”΄", info: "πŸ”΅", neutral: "βšͺ" }; const STEP_MARKERS: Record = { done: "βœ… ", current: "▢️ ", blocked: "β›” " }; /** A readable, non-interactive markdown rendering of an evaluated UI, for clients that can't run it (mobile app, notifications, CLI). Uses the current state values. */ export function toMarkdown(roots: readonly UiNode[]): string { return paragraphs(blocks(roots, false)); } /** compileStreaming/compile + initialState + evaluate + toMarkdown in one call; on compile failure returns the source in a ```ui fence so nothing is lost. */ export function specToMarkdown(source: string, data?: ReadonlyMap): string { const { program } = compile(source); if (program === null) return fence(source, "ui"); return toMarkdown(evaluate(program, initialState(program, data), data).roots); } function hasKind( value: Value | undefined, kind: K, ): value is Extract { return typeof value === "object" && value !== null && "kind" in value && value.kind === kind; } function list(value: Value | undefined): readonly Value[] { return Array.isArray(value) ? value : []; } function children(value: Value | undefined): UiNode[] { return list(value).filter((child) => hasKind(child, "node")); } /** A list item's fields by key; a non-object item stands for its `key` field (e.g. a bare string is a title). */ function fields(item: Value, key: string): { readonly [key: string]: Value } { // Narrowing keeps structurally compatible Action shapes; widen to read by key. return isPlainObject(item) ? item : { [key]: item }; } /** A table lookup that ignores inherited keys, for free-form model text such as an item's `tone`. */ function lookup(table: Record, key: string): string { return Object.hasOwn(table, key) ? table[key] : ""; } function paragraphs(parts: readonly string[]): string { return parts.filter((part) => part !== "").join("\n\n"); } /** Lines under an optional `label:` line; just `label: β€”` when there are none. */ function labelledLines(label: string, lines: readonly string[]): string { if (lines.length === 0) return labelled(label, "β€”"); return [...(label === "" ? [] : [`${label}:`]), ...lines].join("\n"); } /** * One block per node. Consecutive Buttons share one `Options:` line; in a Row, so do consecutive Metrics. * A toned Icon is a dot prefixed to the next one-line block, or a block of its own when nothing follows. */ function blocks(nodes: readonly UiNode[], row: boolean): string[] { const out: string[] = []; let previous: UiNode["type"] | undefined; let icon = ""; for (const node of nodes) { if (node.type === "Icon") { if (icon !== "") out.push(icon); icon = block(node); } else if (node.type === previous && (node.type === "Button" || (row && node.type === "Metric"))) { out[out.length - 1] += ` Β· ${node.type === "Button" ? buttonLabel(node) : block(node)}`; } else { const text = block(node); if (icon !== "" && text !== "" && !text.includes("\n") && !/^[|>#-]/.test(text)) { out.push(`${icon} ${text}`); } else { if (icon !== "") out.push(icon); out.push(text); } icon = ""; } previous = node.type; } if (icon !== "") out.push(icon); return out; } /** A value as text on one logical line: components in block form, lists comma-separated. */ function inline(value: Value | undefined): string { if (value === undefined || value === null) return ""; if (typeof value !== "object") return String(value); if (Array.isArray(value)) return value.map(inline).join(", "); if (hasKind(value, "node")) return value.type === "Button" ? buttonLabel(value) : block(value); if (hasKind(value, "binding")) return inline(value.value); if (hasKind(value, "action")) return ""; return Object.entries(value) .map(([key, item]) => `${key}: ${inline(item)}`) .join(", "); } /** A Button as an option: its label, `⚠ `-marked when destructive; icons have no text form. */ function buttonLabel(node: UiNode): string { return `${node.props.variant === "destructive" ? "⚠ " : ""}${inline(node.props.label)}`; } /** A GFM table cell: one line, `|` escaped. */ function cell(value: Value): string { return inline(value).replace(/\s*\r?\n\s*/g, " ").replace(/\|/g, "\\|"); } function table(columns: readonly Value[], rows: readonly Value[]): string { const header = columns.map(cell); const body = rows.map((row) => (Array.isArray(row) ? row : [row]).map(cell)); const width = body.reduce((widest, cells) => Math.max(widest, cells.length), header.length); if (width === 0) return ""; const line = (cells: readonly string[]) => `| ${Array.from({ length: width }, (_, i) => cells[i] ?? "").join(" | ")} |`; return [line(header), line(Array(width).fill("---")), ...body.map(line)].join("\n"); } /** A fenced block whose fence is longer than any backtick run inside. */ function fence(code: string, language: string): string { const longest = (code.match(/`+/g) ?? []).reduce((max, run) => Math.max(max, run.length), 2); const ticks = "`".repeat(longest + 1); return `${ticks}${language}\n${code.replace(/\n$/, "")}\n${ticks}`; } /** An input's label (its bound state's name when unlabeled) and current value. */ function field(node: UiNode): { readonly label: string; readonly value: Value } { const binding = node.props.value; const name = hasKind(binding, "binding") ? binding.name : ""; const label = inline(node.props.label) || name.charAt(0).toUpperCase() + name.slice(1); return { label, value: hasKind(binding, "binding") ? binding.value : null }; } function labelled(label: string, text: string): string { return label === "" ? text : `${label}: ${text}`; } function finite(value: Value | undefined): value is number { return typeof value === "number" && Number.isFinite(value); } /** A sum without float noise (0.1 + 0.2 β†’ 0.3); null when nothing is a number. */ function total(values: readonly Value[]): number | null { const numbers = values.filter(finite); return numbers.length === 0 ? null : Number(numbers.reduce((sum, n) => sum + n, 0).toPrecision(12)); } /** A Snippet's location: `path`, `path:12` or `path:12-20`. */ function location(path: Value | undefined, from: Value | undefined, to: Value | undefined): string { const start = finite(from) ? from : finite(to) ? 1 : null; const range = start === null ? "" : finite(to) && to !== start ? `:${start}-${to}` : `:${start}`; return `\`${inline(path)}${range}\``; } /** KeyValue pairs from an object, or from `[label, value]` / `{label, value}` list items. */ function pairs(value: Value | undefined): [Value, Value][] { if (value !== undefined && isPlainObject(value)) return Object.entries(value); return list(value).flatMap((item): [Value, Value][] => { if (Array.isArray(item)) return item.length >= 2 ? [[item[0], item[1]]] : []; const pair = fields(item, ""); if (isPlainObject(item) && Object.hasOwn(pair, "label")) return [[pair.label, pair.value ?? null]]; return []; }); } interface TreeEntry { readonly label: string; note: string; folder: boolean; readonly children: TreeEntry[]; } function treeEntry(level: TreeEntry[], label: string): TreeEntry { const existing = level.find((entry) => entry.label === label); if (existing !== undefined) return existing; const entry: TreeEntry = { label, note: "", folder: false, children: [] }; level.push(entry); return entry; } /** Merges path strings ("src/a.ts", "docs/") and `{label, children?, note?}` objects into one tree, in first-seen order. */ function treeEntries(items: readonly Value[], into: TreeEntry[]): TreeEntry[] { for (const item of items) { if (typeof item === "string" || typeof item === "number") { const path = String(item).trim(); const segments = path.split("/").filter((segment) => segment !== "" && segment !== "."); let level = into; segments.forEach((segment, index) => { const entry = treeEntry(level, segment); if (index < segments.length - 1 || path.endsWith("/")) entry.folder = true; level = entry.children; }); } else if (isPlainObject(item)) { const node = fields(item, ""); const raw = inline(node.label).trim(); const label = raw.replace(/\/+$/, ""); if (label === "") continue; const entry = treeEntry(into, label); const note = inline(node.note); if (note !== "") entry.note = note; if (raw !== label || Array.isArray(node.children)) entry.folder = true; treeEntries(list(node.children), entry.children); } } return into; } function treeLines(entries: readonly TreeEntry[], depth: number): string[] { return entries.flatMap((entry) => [ `${" ".repeat(depth)}- ${entry.label}${entry.folder || entry.children.length > 0 ? "/" : ""}${entry.note === "" ? "" : ` β€” ${entry.note}`}`, ...treeLines(entry.children, depth + 1), ]); } /** `m:ss`, or `h:mm:ss` from an hour. */ function clock(seconds: number): string { const whole = Math.round(seconds); const pad = (n: number) => String(n).padStart(2, "0"); const hours = Math.floor(whole / 3600); const minutes = Math.floor((whole % 3600) / 60); return hours > 0 ? `${hours}:${pad(minutes)}:${pad(whole % 60)}` : `${minutes}:${pad(whole % 60)}`; } /** A part's whole-percent share of `sum`; a sliver reads `<1%`, never 0%. Empty without a total. */ function wholeShare(part: number, sum: number): string { if (!(sum > 0)) return ""; const share = part / sum; return share > 0 && share < 0.005 ? "<1%" : `${Math.round(share * 100)}%`; } /** A stage-to-stage rate as on screen: whole from 10%, one decimal below, `<0.1%` for slivers. */ function conversion(ratio: number): string { const percent = ratio * 100; if (percent === 0) return "0%"; if (Math.abs(percent) < 0.1) return "<0.1%"; return `${Number(percent.toFixed(Math.abs(percent) < 10 ? 1 : 0))}%`; } const MONTH_NAMES = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"]; /** * A CalendarHeatmap as text: its total and busiest day, then each day when * there are up to two weeks of them, else a row per month. Dates stay * strings throughout, so no time zone can move one. */ function calendarMarkdown(label: string, days: Value | undefined): string { const entries: [Value | undefined, Value | undefined][] = days !== undefined && isPlainObject(days) ? Object.entries(days) : list(days).map((item) => { if (Array.isArray(item)) return [item[0], item[1] ?? 1]; const day = fields(item, "date"); return [day.date, day.value === undefined ? 1 : day.value]; }); const sums = new Map(); for (const [date, value] of entries) { if (typeof date !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(date) || !finite(value)) continue; sums.set(date, (sums.get(date) ?? 0) + value); } const dates = [...sums.keys()].sort(); if (dates.length === 0) return labelled(label, "β€”"); const busiest = (within: readonly string[]) => within.reduce((best, date) => (sums.get(date)! > sums.get(best)! ? date : best)); const peak = busiest(dates); const summary = labelled( label, `**${total(dates.map((date) => sums.get(date)!))}** total, ${dates[0]} to ${dates[dates.length - 1]}; busiest ${peak} (${sums.get(peak)})`, ); if (dates.length <= 14) { return paragraphs([summary, table(["Date", label || "Value"], dates.map((date) => [date, sums.get(date)!]))]); } const months = new Map(); for (const date of dates) months.set(date.slice(0, 7), [...(months.get(date.slice(0, 7)) ?? []), date]); return paragraphs([ summary, table( ["Month", "Total", "Active days", "Busiest"], [...months].map(([month, within]) => { const top = busiest(within); return [ `${MONTH_NAMES[Number(month.slice(5)) - 1] ?? month} ${month.slice(0, 4)}`, total(within.map((date) => sums.get(date)!)), within.filter((date) => sums.get(date)! > 0).length, `${top} (${sums.get(top)})`, ]; }), ), ]); } function block(node: UiNode): string { const props = node.props; switch (node.type) { case "Card": { const title = inline(props.title); return paragraphs([title === "" ? "" : `**${title}**`, ...blocks(children(props.children), false)]); } case "Details": return paragraphs([`**${inline(props.title)}**`, ...blocks(children(props.children), false)]); case "Row": return paragraphs(blocks(children(props.children), true)); case "Stack": case "Grid": return paragraphs(blocks(children(props.children), false)); case "Divider": return "---"; case "Text": return inline(props.text); case "Draft": { const title = inline(props.title); const body = inline(props.markdown); return paragraphs([title === "" ? "**Draft**" : `**Draft: ${title}**`, body]); } case "Callout": { const title = inline(props.title); const text = inline(props.text); const dot = lookup(TONE_DOTS, inline(props.tone) || "info"); const content = title === "" ? `${dot} ${text}` : paragraphs([`${dot} **${title}**`, text]); // Every line quoted; blank lines stay inside the quote. return content .split("\n") .map((line) => (line === "" ? ">" : `> ${line}`)) .join("\n"); } case "Icon": return lookup(TONE_DOTS, inline(props.tone)); case "Metric": { const note = inline(props.note); return `${inline(props.label)} **${inline(props.value)}**${note === "" ? "" : ` (${note})`}`; } case "Badge": return `${TONE_DOTS[inline(props.tone) || "neutral"]} ${inline(props.text)}`; case "KeyValue": { const entries = pairs(props.pairs); if (entries.length > 3) return table(["", ""], entries); // Two trailing spaces: a hard line break, so the pairs stay on separate lines. return entries.map(([key, value]) => `**${inline(key)}:** ${inline(value)}`).join(" \n"); } case "Image": { const src = inline(props.src).trim(); const alt = inline(props.alt).trim(); if (/^https:\/\//i.test(src)) { const escapes: Record = { " ": "%20", "(": "%28", ")": "%29" }; return `![${alt.replace(/[[\]\\]/g, "\\$&")}](${src.replace(/[ ()]/g, (c) => escapes[c])})`; } // Text clients can't load workspace files: name the image and where it is. return `πŸ–Ό ${alt === "" ? src : `${alt} (${src})`}`; } case "Table": return table(list(props.columns), list(props.rows)); case "Chart": { const unit = inline(props.unit).trim(); const withUnit = (name: string) => (unit === "" ? name : `${name} (${unit})`); const series = props.series; const named: [string, readonly Value[]][] = Array.isArray(series) ? [["Value", series]] : isPlainObject(series) ? Object.entries(series).map(([name, values]) => [name, list(values)]) : []; const labels = list(props.labels); if (props.type === "pie") { // A pie has one series; its slices are shares of the positive total. const [name, values] = named[0] ?? ["Value", []]; const slices = labels.map((_, index) => { const value = values[index]; return finite(value) && value > 0 ? value : 0; }); const sum = slices.reduce((all, slice) => all + slice, 0); return table( ["", withUnit(name), "%"], labels.map((label, index) => [label, values[index] ?? null, wholeShare(slices[index], sum)]), ); } if (props.type === "funnel") { // A funnel has one series too: each stage against the first and the one before. const [name, values] = named[0] ?? ["Value", []]; const first = values[0]; return table( ["", withUnit(name), "% of first", "% of previous"], labels.map((label, index) => { const value = values[index]; const previous = values[index - 1]; return [ label, value ?? null, index > 0 && finite(value) && finite(first) && first > 0 ? conversion(value / first) : "", finite(value) && finite(previous) && previous > 0 ? conversion(value / previous) : "", ]; }), ); } if (props.type === "heatmap") { // Laid out as on screen: labels across, one row per series. return table([unit, ...labels], named.map(([name, values]) => [name, ...labels.map((_, index) => values[index] ?? null)])); } const stacked = props.stacked === true && named.length > 1 && (props.type === "bar" || props.type === "area"); return table( [props.type === "scatter" ? "x" : "", ...named.map(([name]) => withUnit(name)), ...(stacked ? [withUnit("Total")] : [])], labels.map((label, index) => { const values = named.map(([, values]) => values[index] ?? null); return [label, ...values, ...(stacked ? [total(values)] : [])]; }), ); } case "Sparkline": { const values = list(props.values).filter(finite); if (values.length < 2) return values.map(String).join(""); return `${values[0]} β†’ ${values[values.length - 1]} (min ${Math.min(...values)}, max ${Math.max(...values)})`; } case "Progress": { const value = Number(props.value); const max = props.max; const amount = typeof max !== "number" ? `${value}%` : `${value}/${max}${max === 0 ? "" : ` (${Math.round((value / max) * 100)}%)`}`; return labelled(inline(props.label), amount); } case "Steps": return list(props.items) .map((item, index) => { const step = fields(item, "title"); const detail = inline(step.detail); const marker = lookup(STEP_MARKERS, inline(step.status)); return `${index + 1}. ${marker}${inline(step.title)}${detail === "" ? "" : ` β€” ${detail}`}`; }) .join("\n"); case "Timeline": return list(props.items) .map((item) => { const event = fields(item, "title"); const dot = lookup(TONE_DOTS, inline(event.tone)); const head = [inline(event.time), inline(event.title)].filter((part) => part !== "").join(" Β· "); const detail = inline(event.detail); return `- ${dot === "" ? "" : `${dot} `}${head}${detail === "" ? "" : ` β€” ${detail}`}`; }) .join("\n"); case "Tree": return treeLines(treeEntries(list(props.items), []), 0).join("\n"); case "Tabs": { const labels = list(props.labels); return paragraphs( children(props.children).map((child, index) => { const label = inline(labels[index]); return paragraphs([label === "" ? "" : `**${label}**`, block(child)]); }), ); } case "Code": return fence(inline(props.code), inline(props.language)); case "Snippet": { const where = location(props.path, props.from, props.to); const error = inline(props.error); if (error !== "") return `${where} _(error: ${error})_`; return typeof props.code === "string" ? `${where}\n${fence(props.code, inline(props.language))}` : where; } case "Diff": return fence(inline(props.patch), "diff"); case "Diagram": return diagramMarkdown(inline(props.mermaid), props.details); case "File": { const line = inline(props.line); return `\`${inline(props.path)}${line === "" ? "" : `:${line}`}\``; } case "Slider": { const { label, value } = field(node); return labelled(label, `${inline(value) || "β€”"} (${inline(props.min)}–${inline(props.max)})`); } case "Toggle": { const { label, value } = field(node); return labelled(label, value === true ? "on" : "off"); } case "Choice": case "Select": { const { label, value } = field(node); return labelled(label, `${inline(value) || "β€”"} (${list(props.options).map(inline).join(", ")})`); } case "Radio": { const { label, value } = field(node); const options = list(props.options).map((item) => { const option = fields(item, "value"); const picked = value !== null && option.value === value; const detail = inline(option.detail); return `- ${picked ? "β—‰" : "β—‹"} ${inline(option.label ?? option.value)}${detail === "" ? "" : ` β€” ${detail}`}`; }); return labelledLines(label, options); } case "Checklist": { const { label, value } = field(node); const picked = list(value); const items = list(props.options).map((option) => `- [${picked.includes(option) ? "x" : " "}] ${inline(option)}`); return [label === "" ? "" : `${label}:`, ...items].filter((line) => line !== "").join("\n"); } case "ListEditor": { const { label, value } = field(node); return labelledLines( label, list(value).map((item) => `- ${inline(item)}`), ); } case "Stepper": case "Input": case "TextArea": case "DateInput": { const { label, value } = field(node); return labelled(label, inline(value) || "β€”"); } case "Rating": { const { label, value } = field(node); const max = finite(props.max) ? Math.min(10, Math.max(1, Math.round(props.max))) : 5; const stars = finite(value) ? Math.min(max, Math.max(0, Math.round(value))) : 0; return labelled(label, `${"β˜…".repeat(stars)}${"β˜†".repeat(max - stars)} (${stars}/${max})`); } case "Button": return `Options: ${buttonLabel(node)}`; case "Other": return `Options: ${inline(props.label).trim() || "Other…"}`; case "Form": return paragraphs([...blocks(children(props.children), false), `Submit: ${inline(props.submit).trim() || "Send"}`]); case "Timer": { const seconds = props.seconds; return `⏱ ${labelled(inline(props.label), finite(seconds) && seconds > 0 ? `${clock(seconds)} countdown` : "stopwatch")}`; } case "Quiz": return paragraphs( list(props.questions).map((item, index) => { const question = fields(item, "q"); const marker = `${index + 1}. `; const indent = " ".repeat(marker.length); const options = list(question.options); const answer = question.answer; const correct = typeof answer === "number" && Number.isInteger(answer) && answer >= 0 && answer < options.length ? `${String.fromCharCode(65 + answer)}. ${inline(options[answer])}` : ""; const why = inline(question.why); const verdict = [correct, why].filter((part) => part !== "").join(" β€” "); return [ `${marker}${inline(question.q ?? question.question)}`, ...options.map((option, at) => `${indent}- ${String.fromCharCode(65 + at)}. ${inline(option)}`), // A paragraph of its own after the options, so it reads as the reveal rather than another option. ...(verdict === "" ? [] : ["", `${indent}**Answer:** ${verdict}`]), ].join("\n"); }), ); case "Flashcards": return list(props.cards) .map((item) => { const card = fields(item, "front"); const back = inline(card.back); return `- ${inline(card.front)}${back === "" ? "" : ` β†’ ${back}`}`; }) .join("\n"); case "Carousel": return paragraphs(blocks(children(props.children), false)); case "OptionCards": { const { label, value } = field(node); const multiple = Array.isArray(value); const options = list(props.options).flatMap((item) => { const option = fields(item, "value"); const chosen = option.value ?? option.title; if (chosen === undefined || chosen === null) return []; const picked = multiple ? list(value).includes(chosen) : chosen === value; const marker = multiple ? `[${picked ? "x" : " "}]` : picked ? "β—‰" : "β—‹"; const detail = inline(option.detail); return [`- ${marker} ${inline(option.title ?? chosen)}${detail === "" ? "" : ` β€” ${detail}`}`]; }); return labelledLines(label, options); } case "Swatches": { // Unbound it is a palette: no value, no picked marker. const bound = hasKind(props.value, "binding"); const { label, value } = field(node); const colors = list(props.colors).flatMap((item) => { const color = fields(item, "value"); const css = inline(color.value).trim(); if (css === "") return []; const name = inline(color.name).trim(); // Colours compare without case or surrounding space. const picked = typeof value === "string" && value.trim().toLowerCase() === css.toLowerCase(); const marker = !bound ? "" : picked ? "β—‰ " : "β—‹ "; return [`- ${marker}${name === "" ? "" : `${name} `}\`${css}\``]; }); return labelledLines(label, colors); } case "EditableTable": { const { label, value } = field(node); const columns = editableColumns(props.columns); const rows = list(value).map((item) => { const row = fields(item, ""); return columns.map(({ key }) => { const cell = Object.hasOwn(row, key) ? row[key] : null; return typeof cell === "boolean" ? (cell ? "βœ“" : "βœ—") : cell; }); }); return paragraphs([ label === "" ? "" : `${label}:`, rows.length === 0 ? "β€”" : table(columns.map((column) => column.label), rows), ]); } case "FollowUps": { const prompts = list(props.prompts) .map((prompt) => inline(prompt).trim()) .filter((prompt) => prompt !== ""); return prompts.length === 0 ? "" : ["Follow-ups:", ...prompts.map((prompt) => `- ${prompt}`)].join("\n"); } case "Entity": { const name = inline(props.name).trim(); const kind = inline(props.kind); const url = webUrl(inline(props.url), ["http:", "https:"]); // A file image is decoration text clients can't load; an https one shows. const image = remoteImage(inline(props.image), name); return paragraphs([ image ?? "", `**${name}**${Object.hasOwn(ENTITY_KINDS, kind) ? ` Β· ${ENTITY_KINDS[kind]}` : ""}`, inline(props.note).trim(), pairs(props.facts) .map(([key, value]) => `**${inline(key)}:** ${inline(value)}`) .join(" \n"), url === null ? "" : `πŸ”— ${link(url.host.replace(/^www\./i, ""), url)}`, ]); } case "Sources": { const lines = list(props.links).flatMap((item, index) => { const source = fields(item, "url"); const raw = inline(source.url).trim(); // A streaming `{title: …` has not reached its url yet. if (raw === "" && index === list(props.links).length - 1) return []; const marker = `${index + 1}. `; const url = webUrl(raw, ["https:"]); if (url === null) return [`${marker}${raw || "β€”"} _(not an https link)_`]; const domain = url.host.replace(/^www\./i, ""); const title = inline(source.title).trim(); const note = inline(source.note).trim(); const about = [title === "" ? "" : domain, note].filter((part) => part !== "").join(" Β· "); return [`${marker}${link(title || domain, url)}${about === "" ? "" : ` β€” ${about}`}`]; }); return lines.length === 0 ? "" : ["Sources:", ...lines].join("\n"); } case "Hotspots": { const src = inline(props.image).trim(); const points = list(props.points).flatMap((item, index) => { const point = fields(item, "title"); const title = inline(point.title).trim() || `Point ${index + 1}`; const body = inline(point.text).trim(); const marker = `${index + 1}. `; // Continuation lines indented under the item, so a multi-paragraph text stays in it. const text = body.replace(/\n(?=[^\n])/g, `\n${" ".repeat(marker.length)}`); return [`${marker}**${title}**${body === "" ? "" : ` β€” ${text}`}`]; }); return paragraphs([remoteImage(src, "") ?? (src === "" ? "" : `πŸ–Ό ${src}`), points.join("\n")]); } case "ImageSearch": { const query = inline(props.query).trim(); return searchedImage(query, inline(props.alt).trim() || query); } case "Gallery": return paragraphs(list(props.images).map(galleryImage)); case "Map": return placeList(list(props.places), props.route === true); case "Gauge": { const min = finite(props.min) ? props.min : 0; const max = finite(props.max) ? props.max : 100; return labelled(inline(props.label), `**${inline(props.value)}** (${min}–${max})`); } case "CalendarHeatmap": return calendarMarkdown(inline(props.label), props.days); case "SegmentedBar": { const unit = inline(props.unit).trim(); const parts = list(props.parts) .map((part) => fields(part, "label")) .filter((part) => finite(part.value) && part.value >= 0); const sum = parts.reduce((all, part) => all + (part.value as number), 0); return table( ["", unit === "" ? "Value" : `Value (${unit})`, "%"], parts.map((part) => { const dot = lookup(TONE_DOTS, inline(part.tone)); return [`${dot === "" ? "" : `${dot} `}${inline(part.label)}`, part.value, wholeShare(part.value as number, sum)]; }), ); } case "Walkthrough": return paragraphs( list(props.steps).map((item, index) => { const step = fields(item, "body"); const title = inline(step.title).trim(); const code = inline(step.code); return paragraphs([ `**${index + 1}.${title === "" ? "" : ` ${title}`}**`, inline(step.body).trim(), code.trim() === "" ? "" : fence(code, inline(step.language).trim()), ]); }), ); case "List": return list(props.items) .flatMap((item) => { const row = fields(item, "title"); const title = inline(row.title).trim(); if (title === "") return []; const dot = lookup(TONE_DOTS, inline(row.tone)); // A row that opens a link reads as that link; other actions have no text form. const actions: readonly (Value | undefined)[] = Array.isArray(row.action) ? row.action : [row.action]; const url = actions.flatMap((action) => hasKind(action, "action") && action.type === "openUrl" ? [webUrl(action.url, ["http:", "https:"])] : [], )[0] ?? null; const tail = [inline(row.detail).trim(), inline(row.value).trim()].filter((part) => part !== "").join(" Β· "); return [`- ${dot === "" ? "" : `${dot} `}${url === null ? `**${title}**` : link(title, url)}${tail === "" ? "" : ` β€” ${tail}`}`]; }) .join("\n"); case "Calendar": return eventCalendarMarkdown(list(props.events), inline(props.month)); case "Changes": case "Commits": case "PullRequest": case "Threads": return projectMarkdown(node); case "Tests": return testsMarkdown(props.results, inline(props.title)); case "Json": return jsonMarkdown(props.value ?? null, inline(props.label)); case "Plan": return planMarkdown(props.steps, inline(props.submit)); case "Decision": return decisionMarkdown(props.options, props.criteria); case "Estimate": return estimateMarkdown(props.tasks, props.unit); case "Environments": return environmentsMarkdown(); case "Findings": return findingsMarkdown(props.items, inline(props.title)); case "Coverage": return coverageMarkdown(props.report); case "Board": return boardMarkdown(props.items, props.columns, localDay(new Date())); case "Roadmap": return roadmapMarkdown(props.items, localDay(new Date())); case "Status": return statusMarkdown(props.items, localDay(new Date())); case "Benchmark": return benchmarkMarkdown(props.results, inline(props.unit).trim() || null); case "Waterfall": return waterfallMarkdown(props.spans, inline(props.unit).trim() || null); case "Treemap": return treemapMarkdown(props.items, inline(props.unit).trim() || null); case "Logs": return logsMarkdown(props.output, inline(props.command).trim(), props.exit); case "StackTrace": return stackTraceMarkdown(props.trace, inline(props.title).trim()); case "Pipeline": return pipelineMarkdown(props.run); case "Dependencies": return dependenciesMarkdown(props.report); case "Compare": return compareMarkdown(props.images); case "Provenance": return provenanceMarkdown(props.stages, props.expected); case "Acceptance": return acceptanceMarkdown(props.criteria, props.columns); case "Transcript": return transcriptMarkdown(props.tracks, inline(props.audio).trim()); case "Error": return `_(error: ${inline(props.message)})_`; case "Loading": return `_(loading ${inline(props.path)})_`; } } /** EditableTable columns: keys or `{key, label?}`; a bare key is its own label, capitalized. */ function editableColumns(value: Value | undefined): { readonly key: string; readonly label: string }[] { return list(value).flatMap((item) => { const column = fields(item, "key"); const key = inline(column.key).trim(); if (key === "") return []; return [{ key, label: inline(column.label).trim() || key.charAt(0).toUpperCase() + key.slice(1) }]; }); } const ENTITY_KINDS: Record = { product: "Product", place: "Place", person: "Person", org: "Organisation", link: "Link", }; /** An absolute URL with one of `protocols` (`"https:"`) and a host, or null. */ function webUrl(raw: string, protocols: readonly string[]): URL | null { try { const url = new URL(raw.trim()); return protocols.includes(url.protocol) && url.hostname !== "" ? url : null; } catch { return null; } } /** `[label](url)` with the label's brackets escaped and the URL safe inside the parentheses. */ function link(label: string, url: URL): string { return `[${label.replace(/[[\]\\]/g, "\\$&")}](${url.href.replace(/[()]/g, (c) => (c === "(" ? "%28" : "%29"))})`; } /** An https image as markdown (text clients can fetch it); null for files and anything else. */ function remoteImage(src: string, alt: string): string | null { const url = webUrl(src, ["https:"]); return url === null ? null : `!${link(alt, url)}`; } /** A photo an image search found, with its credit (web/commons.ts `FoundImage`). */ export interface SearchedImage { readonly url: string; readonly creator: string; readonly license: string; readonly sourceUrl: string; } /** * The image searches of the rendering in progress, by query. block() is * synchronous, so toMarkdownWithImages can hold them here for one call. */ let searched: ReadonlyMap = new Map(); /** toMarkdown with ImageSearch and Gallery `{query}` items shown as the photos `images` found for them (see imageSearches). */ export function toMarkdownWithImages(roots: readonly UiNode[], images: ReadonlyMap): string { searched = images; try { return toMarkdown(roots); } finally { searched = new Map(); } } /** The image searches in evaluated nodes (ImageSearch queries, Gallery `{query}` items), in order, without repeats. */ export function imageSearches(roots: readonly UiNode[]): string[] { const queries = new Set(); const visit = (value: Value | undefined): void => { if (value === undefined || value === null || typeof value !== "object") return; if (Array.isArray(value)) { value.forEach(visit); } else if (hasKind(value, "node")) { if (value.type === "ImageSearch") queries.add(inline(value.props.query).trim()); if (value.type === "Gallery") { for (const item of list(value.props.images)) { const image = fields(item, "src"); if (inline(image.src).trim() === "") queries.add(inline(image.query).trim()); } } Object.values(value.props).forEach(visit); } else if (isPlainObject(value)) { Object.values(value).forEach(visit); } }; roots.forEach(visit); queries.delete(""); return [...queries]; } /** * A searched photo, then its caption and credit on lines of their own (two * trailing spaces break the line). Without a result (none found, lookups off, * plain toMarkdown) it is named instead. */ function searchedImage(query: string, alt: string, caption = ""): string { const found = searched.get(query); const image = found ? remoteImage(found.url, alt) : null; const source = found ? webUrl(found.sourceUrl, ["https:"]) : null; if (!found || image === null || source === null) return `πŸ–Ό ${caption || alt}`; const credit = `${found.creator}, ${found.license}`.replace(/[*_`[\]\\]/g, "\\$&"); return [image, caption, `_Photo: ${credit}, ${link("Wikimedia Commons", source)}_`].filter((line) => line !== "").join(" \n"); } /** One Gallery item: a path, an https URL, or `{src|query, caption?}`. */ function galleryImage(item: Value): string { const image = fields(item, "src"); const caption = inline(image.caption).trim(); const src = inline(image.src).trim(); const query = inline(image.query).trim(); const alt = inline(image.alt).trim() || caption || query; if (src === "") return query === "" ? "" : searchedImage(query, alt, caption); const remote = remoteImage(src, alt); if (remote === null) return `πŸ–Ό ${caption === "" ? src : `${caption} (${src})`}`; return caption === "" ? remote : `${remote} \n${caption}`; } /** A Map as a numbered list, each place linked on OpenStreetMap: its pin, or a search for its name. */ function placeList(places: readonly Value[], route: boolean): string { const named = places.flatMap((item) => { const place = fields(item, "name"); const name = inline(place.name).trim(); return name === "" ? [] : [{ name, note: inline(place.note).trim(), lat: place.lat, lng: place.lng }]; }); const lines = named.map(({ name, note, lat, lng }, index) => { const located = finite(lat) && finite(lng) && Math.abs(lat) <= 90 && Math.abs(lng) <= 180; const url = located ? new URL(`https://www.openstreetmap.org/?mlat=${lat}&mlon=${lng}#map=15/${lat}/${lng}`) : new URL(`https://www.openstreetmap.org/search?query=${encodeURIComponent(name)}`); return `${index + 1}. **${name}**${note === "" ? "" : ` β€” ${note}`} Β· ${link("OpenStreetMap", url)}`; }); const order = route && named.length > 1 ? `Route: ${named.map((place) => place.name).join(" β†’ ")}` : ""; return paragraphs([order, lines.join("\n")]); } /** * The label a mermaid source gives node `id` (`crank[Crankset]`, `a((Hub))`, * `b{"Ok?"}`), or the id itself. */ function mermaidLabel(source: string, id: string): string { const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); const match = new RegExp(`(?:^|[\\s;&>-])${escaped}\\s*[[({>]+\\s*"?([^"\\])}\\n]+?)"?\\s*[\\])}]`, "m").exec(source); return match?.[1]?.trim() || id; } /** The mermaid fence, then each node's detail under the node's label. */ function diagramMarkdown(source: string, details: Value | undefined): string { const entries = details !== undefined && isPlainObject(details) ? Object.entries(details) : []; return paragraphs([ fence(source, "mermaid"), ...entries.map(([id, detail]) => { const parts = (Array.isArray(detail) ? detail : [detail]).map((part) => hasKind(part, "node") ? block(part) : inline(part).trim(), ); const [first = "", ...rest] = parts.filter((part) => part !== ""); if (first === "") return ""; const label = `**${mermaidLabel(source, id)}**`; // Text joins the label on one line; a component goes under it. const firstIsText = !hasKind(Array.isArray(detail) ? detail[0] : detail, "node"); return paragraphs(firstIsText ? [`${label} β€” ${first}`, ...rest] : [label, first, ...rest]); }), ]); } const WEEKDAY_SHORT = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"]; const MONTH_LONG = new Intl.DateTimeFormat("en-US", { month: "long", year: "numeric", timeZone: "UTC" }); /** `yyyy-mm-dd` as a UTC midnight, so no timezone moves the day; null for anything else. */ function calendarDate(value: Value | undefined): Date | null { const match = typeof value === "string" ? /^\s*(\d{4})-(\d{1,2})-(\d{1,2})(?:$|[T\s])/.exec(value) : null; if (match === null) return null; const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])]; const date = new Date(Date.UTC(year, month - 1, day)); return date.getUTCMonth() === month - 1 && date.getUTCDate() === day ? date : null; } /** A Calendar as its events by month: `**October 2026**` then `- Fri 9 β€” RC 1` lines. */ function eventCalendarMarkdown(items: readonly Value[], month: string): string { const events = items .flatMap((item) => { if (!isPlainObject(item)) return []; const event = fields(item, "date"); const date = calendarDate(event.date); return date === null ? [] : [{ date, title: inline(event.title).trim(), dot: lookup(TONE_DOTS, inline(event.tone)) }]; }) .sort((a, b) => a.date.getTime() - b.date.getTime()); if (events.length === 0) { const shown = calendarDate(`${month.trim()}-01`); return shown === null ? "" : `**${MONTH_LONG.format(shown)}**: no events`; } const months: string[] = []; let current = ""; for (const { date, title, dot } of events) { const heading = MONTH_LONG.format(date); if (heading !== current) { months.push(`**${heading}**`); current = heading; } const line = `- ${WEEKDAY_SHORT[date.getUTCDay()]} ${date.getUTCDate()} β€” ${dot === "" ? "" : `${dot} `}${title || "Event"}`; months[months.length - 1] += `\n${line}`; } return paragraphs(months); } // ── Project components that read BB (Changes, Commits, PullRequest, Threads) ── /** * What BB answered for the rendering in progress, by request key. block() is * synchronous, so toMarkdownWithProject holds them here for one call. */ let projectAnswers: ReadonlyMap = new Map(); /** The BB read a Project node needs, or why its props can't be read; null for other nodes. */ function projectRequest(node: UiNode): Parsed | null { const props = node.props; switch (node.type) { case "Changes": { const target = parseChangesTarget(props.target); if (!target.ok) return target; const paths = parsePathFilter(props.paths); if (!paths.ok) return paths; return { ok: true, value: { kind: "changes", target: target.value, paths: paths.value } }; } case "Commits": return { ok: true, value: { kind: "commits" } }; case "PullRequest": return { ok: true, value: { kind: "pullRequest" } }; case "Threads": { const ids = parseThreadIds(props.ids); return ids.ok ? { ok: true, value: { kind: "threads", ids: ids.value } } : ids; } case "Environments": return { ok: true, value: { kind: "environments" } }; default: return null; } } /** The BB reads the evaluated nodes need (Changes, Commits, PullRequest, Threads), in order, without repeats. */ export function projectRequests(roots: readonly UiNode[]): ProjectRequest[] { const requests = new Map(); const visit = (value: Value | undefined): void => { if (value === undefined || value === null || typeof value !== "object") return; if (Array.isArray(value)) { value.forEach(visit); } else if (hasKind(value, "node")) { const request = projectRequest(value); if (request?.ok) requests.set(projectRequestKey(request.value), request.value); Object.values(value.props).forEach(visit); } else if (isPlainObject(value)) { Object.values(value).forEach(visit); } }; roots.forEach(visit); return [...requests.values()]; } /** toMarkdownWithImages with Changes, Commits, PullRequest and Threads shown as what BB answered (`answers`, by `projectRequestKey`). */ export function toMarkdownWithProject( roots: readonly UiNode[], images: ReadonlyMap, answers: ReadonlyMap, ): string { projectAnswers = answers; try { return toMarkdownWithImages(roots, images); } finally { projectAnswers = new Map(); } } /** Each Project component's name, and what it says without an answer from BB (plain toMarkdown, no thread). */ const PROJECT_TEXT: Record = { Changes: { title: "Changes", unanswered: "_The changes in this thread's checkout: open the reply in BB to see them._" }, Commits: { title: "Commits", unanswered: "_This branch's commits: open the reply in BB to see them._" }, PullRequest: { title: "Pull request", unanswered: "_This branch's pull request: open the reply in BB to see it._" }, Threads: { title: "Threads", unanswered: "_Thread status: open the reply in BB to see it._" }, }; /** Rows a markdown list or table shows before saying how many more there are. */ const MARKDOWN_ROWS = 50; /** "_… and 3 more files_" when rows were left out; `noun` is singular. */ function moreLine(shown: number, total: number, noun: string): string { const more = total - shown; return more > 0 ? `_… and ${more} more ${noun}${more === 1 ? "" : "s"}_` : ""; } function projectMarkdown(node: UiNode): string { const text = PROJECT_TEXT[node.type]; if (text === undefined) return ""; const request = projectRequest(node); if (request === null) return ""; if (!request.ok) return `_(error: ${request.error})_`; const answer = projectAnswers.get(projectRequestKey(request.value)); if (answer === undefined) return text.unanswered; if (!answer.ok) return `**${text.title}** Β· _${answer.message}_`; if ("scope" in answer) return changesMarkdown(answer); if ("commits" in answer) { const limit = parseCommitLimit(node.props.limit); return commitsMarkdown(answer, limit.ok ? limit.value : null); } if ("pullRequest" in answer) return pullRequestMarkdown(answer); // Environments renders through its own case in block(). if ("environments" in answer) return ""; return threadsMarkdown(answer); } function changesMarkdown(view: ChangesView): string { const totals = changeTotals(view.files); const filter = view.filter === null ? "" : ` Β· paths: ${view.filter.join(", ")} (${totals.files} of ${view.totalFiles} files)`; const summary = totals.files === 0 ? "no changes" : `${totals.files} file${totals.files === 1 ? "" : "s"}, +${totals.additions} βˆ’${totals.deletions}`; const header = `**Changes** Β· ${scopeLabel(view.scope)} Β· ${summary}${filter}`; if (totals.files === 0) return header; const rows = view.files.slice(0, MARKDOWN_ROWS).map((file) => { const counted = file.diff !== "binary"; const kind = `${CHANGE_LABEL[file.kind]}${file.untracked ? ", untracked" : ""}${counted ? "" : ", binary"}`; const from = file.previousPath === null ? "" : ` (from \`${file.previousPath}\`)`; return [`\`${file.path}\`${from}`, kind, counted ? `+${file.additions}` : "β€”", counted ? `βˆ’${file.deletions}` : "β€”"]; }); return paragraphs([ header, table(["File", "Change", "+", "βˆ’"], rows), moreLine(rows.length, view.files.length, "file"), view.listTruncated ? "_BB listed only part of the changed files._" : "", ]); } function commitsMarkdown(view: CommitsView, limit: number | null): string { const where = view.onBase || view.ahead === null ? (view.branch ?? "detached HEAD") : `${view.branch ?? "detached HEAD"} Β· ${view.ahead} ahead, ${view.behind} behind ${view.base}`; const header = `**Commits** Β· ${where}`; if (view.onBase) return `${header} Β· _this is the default branch: no branch commits_`; if (view.commits.length === 0) return `${header} Β· no commits since ${view.base}`; const shown = view.commits.slice(0, limit ?? MARKDOWN_ROWS); const lines = shown.map( (commit) => `- \`${commit.shortSha}\` ${commit.subject} β€” ${commit.author}, ${relativeTime(commit.authoredAt, view.takenAt)}`, ); return paragraphs([header, lines.join("\n"), moreLine(shown.length, view.commits.length, "commit")]); } function pullRequestMarkdown(view: PullRequestView): string { const pr = view.pullRequest; if (pr === null) return `**Pull request** Β· ${view.branch === null ? "none" : `none for ${view.branch}`}`; const url = webUrl(pr.url, ["https:"]); const label = `#${pr.number} ${pr.title}`; const counts = checkCounts(pr.checks); const attention = ATTENTION_LABEL[pr.attention]; return [ `**Pull request** ${url === null ? `**${label}**` : link(label, url)}`, PR_STATE_LABEL[pr.state], `${pr.baseRef} ← ${pr.headRef}`, `${CHECKS_LABEL[pr.checks.state]}${counts === "" ? "" : ` (${counts})`}`, REVIEW_LABEL[pr.review.state], MERGEABILITY_LABEL[pr.mergeability], attention === null ? "" : `needs: ${attention}`, ] .filter((part) => part !== "") .join(" Β· "); } function threadsMarkdown(view: ThreadsView): string { const header = view.mode === "subthreads" ? `**Subthreads** (${view.threads.length}${view.truncated ? "+" : ""})` : "**Threads**"; if (view.threads.length === 0) return `${header} Β· none`; const shown = view.threads.slice(0, MARKDOWN_ROWS); const lines = shown.map((thread) => { if (!thread.found) return `- \`${thread.id}\` β€” not found in this project`; const agent = [thread.provider.name ?? thread.provider.id, thread.model, thread.reasoning === null ? null : `${thread.reasoning} reasoning`] .filter((part) => part !== null) .join(", "); const row = [`- **${thread.title}** β€” ${threadActivityLabel(thread)} Β· ${agent} Β· ${relativeTime(thread.updatedAt, view.fetchedAt)}`]; const pending = thread.pending; if (pending !== null) { const asked = pending.text === null ? "" : pending.code && !pending.text.includes("`") ? `: \`${pending.text}\`` : `: ${plainMarkdown(pending.text)}`; const options = pending.options.length === 0 ? "" : ` (${pending.options.map(plainMarkdown).join(" / ")})`; row.push(` - Needs you: ${pending.action}${asked}${options}${pending.more > 0 ? ` Β· ${pending.more} more waiting` : ""}`); } if (thread.lastMessage !== null) row.push(` - Latest message: ${plainMarkdown(previewText(thread.lastMessage.text))}`); return row.join("\n"); }); return paragraphs([header, lines.join("\n"), moreLine(shown.length, view.threads.length, "thread")]); } /** Failures a Tests rendering lists, and the lines and characters of each message it keeps. */ const TEST_FAILURES = 20; const TEST_MESSAGE_LINES = 12; const TEST_MESSAGE_CHARS = 1_500; /** A test run: a summary line, then each failure with where it is and its message (ANSI codes stripped), first lines only. */ function testsMarkdown(results: Value | undefined, title: string): string { const read = readTestRun(results); if (!read.ok) return `_(${read.error})_`; const { tests, counts, ms } = read.run; const dots = [ counts.failed > 0 ? `πŸ”΄ ${counts.failed} failed` : "", counts.passed > 0 ? `🟒 ${counts.passed} passed` : "", counts.skipped > 0 ? `βšͺ ${counts.skipped} skipped` : "", ].filter((part) => part !== ""); const summary = tests.length === 0 ? "No tests ran." : [...dots, ms === null ? "" : formatDuration(ms)].filter((part) => part !== "").join(" Β· "); const failures = tests.filter((test) => test.status === "failed"); const common = commonDirectory(tests.flatMap((test) => (test.file === null ? [] : [test.file]))); const items = failures.slice(0, TEST_FAILURES).map((test, index) => { const where = test.file === null ? "" : ` β€” \`${displayPath(test.file, null, common)}${test.line === null ? "" : `:${test.line}`}\``; const head = `${index + 1}. **${test.name.replace(/[*_`[\]\\]/g, "\\$&")}**${test.detail === null ? "" : ` (${test.detail})`}${where}`; if (test.message === null) return head; const lines = stripAnsi(test.message).replace(/\s+$/, "").split("\n"); let kept = lines.slice(0, TEST_MESSAGE_LINES).join("\n"); if (kept.length > TEST_MESSAGE_CHARS) kept = `${kept.slice(0, TEST_MESSAGE_CHARS)}…`; else if (lines.length > TEST_MESSAGE_LINES) kept += "\n…"; return `${head}\n${fence(kept, "").replace(/^/gm, " ")}`; }); const rest = failures.length - items.length; return paragraphs([ title === "" ? summary : `**${title}** β€” ${summary}`, items.length === 0 ? "" : `Failures:\n${items.join("\n")}`, rest > 0 ? `…and ${rest} more ${rest === 1 ? "failure" : "failures"}` : "", ]); } /** Lines of pretty-printed JSON a Json rendering keeps. */ const JSON_LINES = 60; /** A value as a pretty-printed json fence, cut at JSON_LINES with a note of how much was left out. */ function jsonMarkdown(value: Value, label: string): string { const lines = (JSON.stringify(value, null, 2) ?? "null").split("\n"); const kept = lines.length > JSON_LINES ? [...lines.slice(0, JSON_LINES), "…"] : lines; return paragraphs([ label === "" ? "" : `**${label}**`, fence(kept.join("\n"), "json"), lines.length > JSON_LINES ? `_(first ${JSON_LINES} of ${lines.length} lines)_` : "", ]); } const RISK_TEXT: Record = { low: "low risk", medium: "medium risk", high: "**high risk**" }; /** A Plan as a numbered list: each step with its risk and estimate, detail and files below; the total and the approve label. */ function planMarkdown(value: Value | undefined, submit: string): string { const { steps, error } = readPlan(value); if (error !== null) return `_(${error})_`; if (steps.length === 0) return "**Plan** Β· no steps"; const { total, unparsed, mixed } = planTotal(steps, initialChecks(steps)); const size = total === null ? "" : ` Β· ${formatQuantity(total)}${unparsed > 0 ? ` + ${unparsed} unsized` : ""}${steps.some((step) => step.optional) ? " without optional steps" : ""}`; const lines = steps.slice(0, MARKDOWN_ROWS).flatMap((step, index) => { const meta = [step.risk === null ? "" : RISK_TEXT[step.risk], step.estimate === null ? "" : step.amount === null ? step.estimate : formatQuantity(step.amount)] .filter((part) => part !== "") .join(" Β· "); return [ `${index + 1}. ${step.optional ? "_(optional)_ " : ""}${step.title}${meta === "" ? "" : ` Β· ${meta}`}`, ...(step.detail === null ? [] : [` ${step.detail.replace(/\s*\r?\n\s*/g, " ")}`]), ...(step.files.length === 0 ? [] : [` ${step.files.map((file) => `\`${file.path}${file.line === null ? "" : `:${file.line}`}\``).join(" ")}`]), ]; }); return paragraphs([ `**Plan** Β· ${steps.length} ${steps.length === 1 ? "step" : "steps"}${size}${mixed ? " Β· estimates mix points and time" : ""}`, lines.join("\n"), moreLine(Math.min(steps.length, MARKDOWN_ROWS), steps.length, "step"), `Submit: ${submit.trim() || "Approve plan"}`, ]); } /** A Decision as its verdict, the score matrix with weights and weighted scores (spec weights), pros and cons, and the options to send. */ function decisionMarkdown(options: Value | undefined, criteria: Value | undefined): string { const read = readDecision(options, criteria); if (!read.ok) return `_(${read.error})_`; const model = read.model; if (model.options.length === 0) return "**Decision** Β· no options"; const weights = model.criteria.map((criterion) => criterion.weight); const ranked = rankOptions(model, weights); const lead = leaderMargin(ranked); const score = (total: number) => String(round(total, 2)); const top = ranked[0]; const leader = model.options[top.index].name; const verdict = lead !== null && lead.tied.length > 0 ? `${joinAnd([leader, ...lead.tied.map((index) => model.options[index].name)])} are tied at ${score(top.total)} of ${model.scale}` : `${leader} leads with ${score(top.total)} of ${model.scale}${ranked.length > 1 ? `, ${score(lead?.margin ?? 0)} ahead of ${model.options[ranked[1].index].name}` : ""}`; const rows: Value[] = [ ...model.criteria.map((criterion, index): Value => [ criterion.name, formatAmount(criterion.weight), ...model.options.map((option) => (option.scores[index] === null ? "β€”" : formatAmount(option.scores[index] ?? 0))), ]), ["**Weighted score**", "", ...model.options.map((_, index) => { const entry = ranked.find((candidate) => candidate.index === index); return entry === undefined ? "" : index === top.index ? `**${score(entry.total)}**` : score(entry.total); })], ]; const notes = model.options.flatMap((option) => { const parts = [...option.pros.map((pro) => `+ ${pro}`), ...option.cons.map((con) => `βˆ’ ${con}`), ...(option.note === null ? [] : [option.note])]; return parts.length === 0 ? [] : [`- **${option.name}**: ${parts.join("; ")}`]; }); return paragraphs([ `**Decision** Β· ${verdict}`, table(["Criterion", "Weight", ...model.options.map((option) => option.name)], rows), notes.join("\n"), model.issues.map((issue) => `_${issue}_`).join("\n"), `Options: ${ranked.map((entry) => `Go with ${model.options[entry.index].name}`).join(" Β· ")}`, ]); } /** An Estimate as its totals line (PERT mean, P50/P80/P90, range) and a table of the tasks; invalid rows say why. */ function estimateMarkdown(value: Value | undefined, unitValue: Value | undefined): string { const read = readEstimate(value); if (read.error !== null) return `_(${read.error})_`; if (read.tasks.length === 0) return "**Estimate** Β· no tasks"; const unit = estimateUnit(unitValue); const estimates = read.tasks.map(estimateTask); const totals = estimateTotals(estimates); const amount = (number: number | null) => (number === null ? "β€”" : formatAmount(number)); const summary = totals.count === 0 ? "no task has a usable low and high" : [ `expected **${formatWithUnit(totals.mean, unit)}**`, `P50 ${formatWithUnit(totals.p50, unit)}`, `P80 ${formatWithUnit(totals.p80, unit)}`, `P90 ${formatWithUnit(totals.p90, unit)}`, `range ${formatAmount(totals.low)}–${formatWithUnit(totals.high, unit)}`, ].join(" Β· "); const shown = estimates.slice(0, MARKDOWN_ROWS); return paragraphs([ `**Estimate** Β· ${read.tasks.length} ${read.tasks.length === 1 ? "task" : "tasks"} Β· ${summary}`, table( ["Task", `Low (${unit})`, "Likely", "High", "PERT mean"], shown.map((estimate): Value => [ estimate.task.title, amount(estimate.task.low), estimate.task.likely === null && estimate.error === null ? `(${amount(estimate.likely)})` : amount(estimate.task.likely), amount(estimate.task.high), estimate.error === null ? formatAmount(estimate.mean) : `⚠ not counted: ${estimate.error}`, ]), ), moreLine(shown.length, estimates.length, "task"), ]); } // ── Environments ──────────────────────────────────────────────────────────── /** Thread lines an environment lists under it in markdown. */ const ENVIRONMENT_THREAD_LINES = 3; /** The project's environments as BB answered (the default view: those with live threads), each with its git line and threads. */ function environmentsMarkdown(): string { const answer = projectAnswers.get(projectRequestKey({ kind: "environments" })); if (answer === undefined) return "_This project's environments, their threads and changes: open the reply in BB to see them._"; if (!answer.ok) return `**Environments** Β· _${answer.message}_`; if (!("environments" in answer)) return ""; const all = answer.environments; if (all.length === 0) return "**Environments** Β· none in this project"; const { shown, filtered } = defaultEnvironments(all); const running = all.reduce((sum, environment) => sum + environment.threadCounts.running, 0); const header = [ "**Environments**", filtered ? `${shown.length} with live threads of ${all.length}` : `${all.length}`, running > 0 ? `${running} running` : "", ] .filter((part) => part !== "") .join(" Β· "); const rows = shown.slice(0, MARKDOWN_ROWS); const items = rows.map((environment) => environmentItem(environment, answer.fetchedAt)); const left = all.length - rows.length; return paragraphs([ header, items.join("\n"), left > 0 ? `_… and ${left} more environment${left === 1 ? "" : "s"}${filtered ? " without live threads" : ""}_` : "", ]); } function environmentItem(environment: EnvironmentInfo, now: number): string { const title = environmentTitle(environment); const life = LIFE_LABEL[environment.life]; const kind = [kindLabel(environment), environment.current ? "this thread" : "", life ?? ""].filter((part) => part !== "").join(", "); const parts = [ `**${title.replace(/[*_`[\]\\]/g, "\\$&")}** (${kind})`, ...environmentGit(environment), threadSummary(environment), environment.activeAt === null ? "" : relativeTime(environment.activeAt, now), ]; const live = liveThreads(environment).slice(0, ENVIRONMENT_THREAD_LINES); const threads = live.map((thread) => ` - ${thread.subthread ? "↳ " : ""}${thread.title.replace(/[*_`[\]\\]/g, "\\$&")} β€” ${threadStatusLabel(thread)}`); return [`- ${parts.filter((part) => part !== "").join(" Β· ")}`, ...threads].join("\n"); } /** The git facts of an environment's detail: changes, position, pull request; or why they couldn't be read. */ function environmentGit(environment: EnvironmentInfo): string[] { const detail = environment.detail; if (detail === null) return []; const checkout = detail.checkout; if (!checkout.ok) return [`_${checkout.message}_${checkout.path === null ? "" : ` (\`${checkout.path}\`)`}`]; const position = checkout.checkout === "detached" ? `detached ${checkout.head ?? ""}`.trim() : checkout.onBase ? checkout.base === checkout.defaultBranch ? "default branch" : `on base ${checkout.base}` : aheadBehindLabel(checkout); const pull = detail.pull; let pr = ""; if (pull !== null && !pull.ok) pr = "pull request unknown"; else if (pull !== null && pull.pullRequest === null) pr = "no pull request"; else if (pull !== null && pull.pullRequest !== null) { const request = pull.pullRequest; const url = webUrl(request.url, ["https:"]); const label = `#${request.number}`; const checks = request.state === "open" || request.state === "draft" ? `, ${CHECKS_LABEL[request.checks.state].toLowerCase()}` : ""; pr = `PR ${url === null ? label : link(label, url)} ${PR_STATE_LABEL[request.state]}${checks}`; } return [uncommittedLabel(checkout), position, pr]; } // --------------------------------------------------------------------------- // Findings and Coverage const SEVERITY_DOTS: Record = { critical: "πŸ”΄", high: "πŸ”΄", medium: "🟠", low: "πŸ”΅", info: "βšͺ" }; /** Markdown emphasis characters escaped outside `code spans`, so tool messages read as written. */ function escapeProse(text: string): string { return text .split(/(`[^`\n]*`)/) .map((part, index) => (index % 2 === 1 ? part : part.replace(/[*_[\]\\<>]/g, "\\$&"))) .join(""); } /** * Findings as `file:line severity title (rule)` lines, most severe first, under a count per severity; a review leads * with its verdict and what is open, counts per status, and says where each finding stands. */ function findingsMarkdown(items: Value | undefined, title: string): string { const read = readFindings(items); if (!read.ok) return `_(${read.error})_`; const { findings, scale, tool, review } = read.report; const counts = countSeverities(findings); const summary = findings.length === 0 ? "No findings." : SEVERITIES.filter((severity) => counts[severity] > 0) .map((severity) => `${SEVERITY_DOTS[severity]} ${severityCount(severity, scale, counts[severity])}`) .join(" Β· "); const subject = review?.subject == null ? null : `${review.subject} review`; const heading = title !== "" ? title : (subject ?? (findings.length === 1 ? "1 finding" : `${findings.length} findings`)); const header = [`**${heading}**`, summary, tool ?? ""].filter((part) => part !== "").join(" β€” "); const verdict = verdictHeadline(read.report); const verdictLine = verdict === null ? "" : `${{ good: "🟒", warn: "🟠", bad: "πŸ”΄" }[verdict.tone]} **${verdict.text}**`; const statuses = statusCounts(findings) .map((entry) => entry.text) .join(" Β· "); const common = commonDirectory(findings.flatMap((item) => (item.file === null ? [] : [item.file]))); const sorted = sortFindings(findings); const lines = sorted.slice(0, MARKDOWN_ROWS).map((item) => { const where = item.file === null ? "" : `\`${displayPath(item.file, null, common)}${item.line === null ? "" : `:${item.line}${item.column === null ? "" : `:${item.column}`}`}\` `; const url = item.url === null ? null : webUrl(item.url, ["https:", "http:"]); const rule = item.rule === null ? "" : ` (${url === null ? `\`${item.rule}\`` : link(item.rule, url)})`; const status = item.status === null ? "" : ` β€” _${escapeProse(statusSentence(item))}_`; return `- ${where}${severityLabel(item.severity, scale)}: ${escapeProse(item.title)}${rule}${status}`; }); return paragraphs([header, verdictLine, statuses, lines.join("\n"), moreLine(lines.length, sorted.length, "finding")]); } /** Uncovered ranges a Coverage row lists before "…". */ const COVERAGE_RANGES = 8; /** The headline percentage with its tone, the other metrics, then the files with uncovered lines, most first. */ function coverageMarkdown(report: Value | undefined): string { const read = readCoverage(report); if (!read.ok) return `_(${read.error})_`; const { total, unit, files } = read.report; const main = headline(total, unit); const value = percent(main); const tones: Record = { good: "🟒", warn: "🟠", bad: "πŸ”΄" }; const lead = value === null || main === null ? `**Coverage** β€” nothing to cover` : `**Coverage** β€” ${tones[coverageTone(value)]} **${formatPercent(value)}** of ${unit} (${main.covered.toLocaleString("en-US")} of ${main.total.toLocaleString("en-US")})`; const others = (["statements", "branches", "functions"] as const) .filter((metric) => !(metric === "statements" && unit === "statements")) .flatMap((metric) => { const share = percent(total[metric]); return share === null ? [] : [`${metric} ${formatPercent(share)}`]; }); const common = commonDirectory(files.map((file) => file.path)); const missing = mostUncovered(files, unit).filter((file) => file.missed > 0); const shown = missing.slice(0, MARKDOWN_ROWS); const rows = shown.map((file) => { const share = percent(headline(file, unit)); const ranges = file.uncovered === null ? "" : `: ${file.uncovered.slice(0, COVERAGE_RANGES).map(rangeLabel).join(", ")}${file.uncovered.length > COVERAGE_RANGES ? ", …" : ""}`; return [`\`${displayPath(file.path, null, common)}\``, share === null ? "β€”" : formatPercent(share), `${file.missed.toLocaleString("en-US")}${ranges}`]; }); const covered = files.length - missing.length; return paragraphs([ [lead, ...others].join(" Β· "), rows.length === 0 ? "" : table(["File", unit === "lines" ? "Lines" : "Statements", `Uncovered ${unit}`], rows), moreLine(shown.length, missing.length, "file"), covered > 0 && missing.length > 0 ? `_${covered} more ${covered === 1 ? "file" : "files"} fully covered_` : "", ]); } /** Cards listed per Board column before "… and N more". */ const BOARD_COLUMN_ROWS = 20; const BOARD_TITLE: Record = { list: ["Board", "item", "items"], tasks: ["Tasks", "task", "tasks"], issues: ["Issues", "issue", "issues"], pulls: ["Pull requests", "pull request", "pull requests"], }; /** One card: `` `KEY` title `` (linked when it has a URL), then priority, owners, labels, due and live agents. */ function boardCardLine(card: BoardCard, today: number): string { const url = card.url === null ? null : webUrl(card.url, ["http:", "https:"]); const parts: string[] = []; if (card.priority !== null && card.priority !== "none") parts.push(card.priority === "urgent" ? "‼️ urgent" : card.priority); if (card.owners.length > 0) parts.push(card.owners.join(", ")); if (card.labels.length > 0) parts.push(card.labels.map((label) => label.name).join(", ")); if (card.due !== null) { parts.push(cardLate(card, today) ? `**due ${formatDay(card.due, today)} (${relativeDue(card.due, today).text})**` : `due ${formatDay(card.due, today)}`); } if (card.parent !== null) parts.push(`sub-task of ${card.parent}`); if (card.agents > 0) parts.push(`🟒 ${card.agents} ${card.agents === 1 ? "agent" : "agents"} working`); const title = url === null ? card.title : link(card.title, url); return `- ${card.key === null ? "" : `\`${card.key}\` `}${title}${parts.length === 0 ? "" : ` Β· ${parts.join(" Β· ")}`}`; } /** A Board as a list per column, in the board's column order, with counts. */ function boardMarkdown(items: Value | undefined, columns: Value | undefined, today: number): string { const read = readBoard(items, columns); if (!read.ok) return `_(${read.error})_`; const board = read.value; const [title, one, many] = BOARD_TITLE[board.source]!; const notes = [ `${board.total}${board.truncated ? "+" : ""} ${board.total === 1 ? one : many}`, board.hidden > 0 ? `${board.hidden} in other columns not shown` : "", board.skipped > 0 ? `${board.skipped} without a title left out` : "", ].filter((note) => note !== ""); return paragraphs([ `**${title}** Β· ${notes.join(" Β· ")}`, ...board.columns.map((column) => { const shown = column.cards.slice(0, BOARD_COLUMN_ROWS); return [ `**${column.label}** (${column.cards.length})`, ...(shown.length === 0 ? ["_none_"] : shown.map((card) => boardCardLine(card, today))), ...(shown.length < column.cards.length ? [moreLine(shown.length, column.cards.length, one)] : []), ].join("\n"); }), ]); } const ROADMAP_MARKS: Record = { done: "βœ…", active: "πŸ”΅", planned: "βšͺ", blocked: "β›”", "at-risk": "🟠" }; /** A Roadmap as its lanes, each item with its dates, status, progress, owner and what it comes after; late items marked. */ function roadmapMarkdown(items: Value | undefined, today: number): string { const read = readRoadmap(items, today); if (!read.ok) return `_(${read.error})_`; const roadmap = read.value; if (roadmap.items.length === 0) return "**Roadmap** Β· no items"; const first = Math.min(...roadmap.items.map((item) => item.start)); const last = Math.max(...roadmap.items.map((item) => item.end)); const late = roadmap.items.filter((item) => item.late).length; const header = [ `**Roadmap** Β· ${formatRange(first, last, today)}`, `${roadmap.items.length} ${roadmap.items.length === 1 ? "item" : "items"}`, late > 0 ? `${late} late` : "", ].filter((part) => part !== ""); const byIndex = new Map(roadmap.items.map((item) => [item.index, item])); const lanes = roadmap.lanes.map((lane) => { const lines = lane.items.map((item) => { const when = item.milestone ? `${formatDay(item.start, today)} (milestone)` : `${formatRange(item.start, item.end, today)} (${formatDays(itemDays(item))})`; const parts = [when]; if (!item.milestone) parts.push(ROADMAP_STATUS_LABEL[item.status].toLowerCase()); if (item.progress !== null && !item.milestone && item.status !== "done") parts.push(`${Math.round(item.progress)}%`); if (item.owner !== null) parts.push(item.owner); if (item.after !== null) { const before = item.afterIndex === null ? undefined : byIndex.get(item.afterIndex); parts.push(before === undefined ? `after ${item.after}` : `after ${before.title}${item.overlap ? " (overlaps it)" : ""}`); } if (item.late) parts.push(`**late: ${item.milestone ? "was due" : "ended"} ${formatDay(item.end, today)}**`); return `- ${item.milestone ? "β—†" : ROADMAP_MARKS[item.status]} ${item.title} β€” ${parts.join(" Β· ")}`; }); return [...(lane.name === "" ? [] : [`**${lane.name}**`]), ...lines].join("\n"); }); const skipped = roadmap.skipped.length === 0 ? "" : `_Left out (no usable dates): ${roadmap.skipped.map((skip) => `${skip.title} (${skip.reason})`).join(", ")}_`; return paragraphs([header.join(" Β· "), ...lanes, skipped]); } const HEALTH_MARKS: Record = { "off-track": "πŸ”΄", blocked: "β›”", "at-risk": "🟠", "on-track": "🟒", "not-started": "βšͺ", done: "βœ…", }; /** A Status report: the summary, then one line per item worst first, its note indented under it. */ function statusMarkdown(items: Value | undefined, today: number): string { const read = readStatus(items, today); if (!read.ok) return `_(${read.error})_`; const report = read.value; if (report.items.length === 0) return "**Status** Β· nothing to report"; const lines = report.items.slice(0, MARKDOWN_ROWS).map((item) => { const parts = [item.status === null ? (item.given ?? "no status") : HEALTH_LABEL[item.status]]; if (item.progress !== null) parts.push(`${Math.round(item.progress)}%`); if (item.owner !== null) parts.push(item.owner); if (item.due !== null) { const due = relativeDue(item.due, today); parts.push(item.status === "done" ? formatDay(item.due, today) : item.late ? `**${due.text}**` : `${due.text} (${formatDay(item.due, today)})`); } const mark = item.status === null ? "βšͺ" : HEALTH_MARKS[item.status]; const note = item.note === null ? [] : item.note.split(/\r?\n/).map((line) => ` ${line}`); return [`- ${mark} **${item.name}** β€” ${parts.join(" Β· ")}`, ...note].join("\n"); }); return paragraphs([`**Status** Β· ${healthSummary(report)}`, lines.join("\n"), moreLine(Math.min(report.items.length, MARKDOWN_ROWS), report.items.length, "item")]); } const VERDICT_DOTS: Record = { better: "🟒", worse: "πŸ”΄", same: "βšͺ" }; /** One ranked run: `1. \`cmd\` β€” 7.8 ms Β± 0.75 ms (min … max) Β· 3.92 Β± 0.44 Γ— slower`. */ function runLine(run: Run, rank: number, unit: string): string { const spread = run.stddev === null ? "" : ` Β± ${perfAmount(run.stddev, unit, 2, run.mean)}`; const range = run.min === run.max ? "" : ` (${perfAmount(run.min, unit)} … ${perfAmount(run.max, unit)})`; const relative = rank === 1 ? "fastest" : `${formatRatio(run.ratio, run.ratioStddev)} Γ— slower`; return `${rank}. \`${run.name}\` β€” ${perfAmount(run.mean, unit)}${spread}${range} Β· ${relative}${run.failed ? " Β· exited non-zero" : ""}`; } /** Before/after rows as a table with each change and its verdict (rows measured under different conditions say so instead); ranked runs (hyperfine, vitest bench) as numbered lists per group; every run of an experiment as a table per group. */ function benchmarkMarkdown(results: Value | undefined, unit: string | null): string { const read = readBenchmark(results, unit); if (!read.ok) return `_(${read.error})_`; const report = read.report; if (report.kind === "all-runs") return allRunsMarkdown(report); if (report.kind === "compare") { if (report.rows.length === 0) return "**Benchmark** Β· no results to compare"; const { better, worse, same } = report.counts; const counts = [ better > 0 ? `${better} ${report.words.better}` : "", worse > 0 ? `${worse} ${report.words.worse}` : "", same > 0 ? `${same} within noise` : "", report.incomparable > 0 ? `${report.incomparable} not comparable (conditions differ)` : "", report.geomean === null || Math.abs(1 - report.geomean) < 0.0005 ? "" : `${Math.abs((1 - report.geomean) * 100).toFixed(1)}% ${report.geomean < 1 ? report.words.better : report.words.worse} overall (geometric mean)`, ].filter((part) => part !== ""); const shown = report.rows.slice(0, MARKDOWN_ROWS); const withConditions = report.rows.some((row) => row.comparability !== null); const amount = (value: number, samples: readonly number[], rowUnit: string | null) => `${perfAmount(value, rowUnit)}${samples.length > 1 ? ` (mean of ${samples.length})` : ""}`; const rows = shown.map((row) => { const change = row.percent === null ? formatDelta(row.delta, row.unit) : `${formatChange(row.percent)} (${formatDelta(row.delta, row.unit)})`; return [ row.better === "higher" ? `${row.name} (higher is better)` : row.name, amount(row.before, row.beforeSamples, row.unit), amount(row.after, row.afterSamples, row.unit), row.comparable ? `${VERDICT_DOTS[row.verdict]} ${change}` : `⚠️ not comparable Β· measured ${change}`, ...(withConditions ? [comparisonConditions(row, report.shared)] : []), ]; }); const shared = formatConditions(report.shared); return paragraphs([ `**Benchmark** Β· ${counts.join(" Β· ")}`, shared === "" ? "" : `Same conditions for every row: ${shared}`, table(["", "Before", "After", "Change", ...(withConditions ? ["Conditions"] : [])], rows), moreLine(shown.length, report.rows.length, "row"), ]); } const groups = report.groups.filter((group) => group.runs.length > 0); if (groups.length === 0) return "**Benchmark** Β· no results"; return paragraphs( groups.map((group) => { const [fastest, ...slower] = group.runs; const lead = slower.slice(0, 3).map((run) => `${formatRatio(run.ratio, run.ratioStddev)} Γ— faster than \`${run.name}\``); const title = `**${group.name ?? "Benchmark"}** Β· \`${fastest.name}\` is fastest${lead.length === 0 ? "" : `: ${lead.join(", ")}`}`; const shown = group.runs.slice(0, MARKDOWN_ROWS); return paragraphs([title, shown.map((run, index) => runLine(run, index + 1, report.unit)).join("\n"), moreLine(shown.length, group.runs.length, "run")]); }), ); } /** One span: indented by depth, its name, status and size for requests, start β†’ end and duration; β—† on the critical path. */ function spanLine(span: Span, critical: boolean): string { const request = span.request; const status = request === null ? "" : request.status > 0 ? ` ${request.status}` : ` ${request.failure ?? "failed"}`; const size = request === null ? null : (request.transfer ?? request.size); const parts = [`${formatMs(span.start)} β†’ ${formatMs(span.end)} (${formatMs(span.end - span.start)})`, size === null ? "" : formatBytes(size), span.detail ?? ""].filter((part) => part !== ""); return `${" ".repeat(span.depth)}- ${span.failed ? "πŸ”΄ " : ""}\`${span.name}\`${status} Β· ${parts.join(" Β· ")}${critical ? " β—†" : ""}`; } /** A waterfall as text: the total, failures and critical path, then each span (nested) with its times. */ function waterfallMarkdown(spans: Value | undefined, unit: string | null): string { const read = readWaterfall(spans, unit); if (!read.ok) return `_(${read.error})_`; const data = read.waterfall; const counted = data.spans.filter((span) => !span.track); const noun = data.source === "har" ? "request" : data.source === "trace" ? "event" : "span"; if (counted.length === 0) return `**Waterfall** Β· no ${noun}s`; const failed = counted.filter((span) => span.failed).length; const header = [ `**Waterfall** Β· ${counted.length} ${noun}${counted.length === 1 ? "" : "s"} Β· ${formatMs(data.total)}`, failed > 0 ? `${failed} failed` : "", data.critical.length > 0 ? `critical path ${formatMs(data.criticalMs)} (β—†)` : "", ...data.markers.map((marker) => `${marker.label} ${formatMs(marker.at)}`), ].filter((part) => part !== ""); const onPath = new Set(data.critical); const shown = data.spans.slice(0, MARKDOWN_ROWS); // Thread rows of a trace count among the rows left out, so the note says rows. return paragraphs([header.join(" Β· "), shown.map((span) => spanLine(span, onPath.has(span.index))).join("\n"), moreLine(shown.length, data.spans.length, "row")]); } /** Children a Treemap rendering lists per level. */ const TREEMAP_TOP = 15; const TREEMAP_INNER = 5; /** A treemap as a nested list: the largest groups with size and share, and the largest items inside each. */ function treemapMarkdown(items: Value | undefined, unit: string | null): string { const read = readTreemap(items, unit); if (!read.ok) return `_(${read.error})_`; const { root, unit: shownUnit } = read.treemap; if (root.value <= 0) return "**Treemap** Β· nothing to show"; const line = (node: TreeNode, depth: number) => `${" ".repeat(depth)}- ${node.name} β€” ${perfAmount(node.value, shownUnit)} (${formatShare(node.value, root.value)})`; const lines = root.children.slice(0, TREEMAP_TOP).flatMap((node) => [ line(node, 0), ...node.children.slice(0, TREEMAP_INNER).map((child) => line(child, 1)), ...(node.children.length > TREEMAP_INNER ? [` - _… and ${node.children.length - TREEMAP_INNER} more_`] : []), ]); const name = root.name === "" ? "" : ` Β· ${root.name}`; return paragraphs([ `**Treemap**${name} Β· ${perfAmount(root.value, shownUnit)} Β· ${root.children.length} ${root.children.length === 1 ? "item" : "items"}`, lines.join("\n"), moreLine(Math.min(root.children.length, TREEMAP_TOP), root.children.length, "item"), ]); } /** Errors (an error and its causes) a StackTrace's markdown lists, and frames per error. */ const TRACE_SECTIONS = 6; const TRACE_FRAMES = 12; /** Lines from the end of a Logs output its markdown shows. */ const LOG_TAIL = 30; const LOG_LINE_CHARS = 300; /** `fn (path:line:col)`, paths relative to what the app's frames share; a runtime frame as printed (`Array.map ()`). */ function traceFrameLine(frame: TraceFrame, common: string): string { const location = frame.location; if (location === null) return frame.text.replace(/^at\s+/, ""); const where = `${displayPath(location.path, null, common)}:${location.line}${location.column === null ? "" : `:${location.column}`}`; return frame.fn === null ? where : `${frame.fn} (${where})`; } /** * An error and its causes: per error a line with its type and message, then a * block with the rest of the message and its frames (innermost first, the * first frame of the app's own code marked `β†’`, dependency runs folded). */ function stackTraceMarkdown(value: Value | undefined, title: string): string { const read = readTrace(value); if (!read.ok) return `_(${read.error})_`; const { sections } = read.trace; const common = commonDirectory( sections.flatMap((s) => s.frames.flatMap((f) => (f.app && f.location?.linkable ? [f.location.path.replace(/^file:\/\//, "")] : []))), ); const places = memberPlaces(sections); const parts = sections.slice(0, TRACE_SECTIONS).map((section, index) => { const label = relationLabel(section.relation, places[index]); const [first, ...rest] = section.message.split("\n"); const type = section.type === "" ? "" : `**${section.type}**`; const head = `${label === "" ? "" : `${label}: `}${type}${first === "" ? "" : `${type === "" ? "" : ": "}${first}`}` || "**Error**"; const marked = section.frames.findIndex((f) => f.app); const rows = frameRows(section.frames, new Set()); const lines = rows .slice(0, TRACE_FRAMES) .map((row) => row.type === "fold" ? ` … ${row.count} library frames` : `${row.index === marked ? "β†’" : " "} ${traceFrameLine(section.frames[row.index], common)}`, ); if (rows.length > TRACE_FRAMES) lines.push(` … ${rows.length - TRACE_FRAMES} more`); if (section.omitted > 0) lines.push(` … ${section.omitted} more as in ${read.trace.language === "java" ? "the error above" : "the cause"}`); const body = [...rest, ...(rest.length > 0 && lines.length > 0 ? [""] : []), ...lines]; const fields = section.fields.map(([key, text]) => `${key} ${text}`).join(" Β· "); return paragraphs([fields === "" ? head : `${head} \n${fields}`, body.length === 0 ? "" : fence(body.join("\n"), "")]); }); return paragraphs([title === "" ? "" : `**${title}**`, ...parts, moreLine(Math.min(sections.length, TRACE_SECTIONS), sections.length, "error")]); } /** A command's output: the command, exit code and counts, the last lines (where a failure usually is, repeats folded), and the first error when it is earlier. */ function logsMarkdown(value: Value | undefined, command: string, exit: Value | undefined): string { const read = readLogs(value); if (!read.ok) return `_(${read.error})_`; const { lines, counts, context, utc } = read.output; const clip = (text: string) => (text.length > LOG_LINE_CHARS ? `${text.slice(0, LOG_LINE_CHARS - 1)}…` : text); const nouns: Record = { fatal: "fatal", error: "error", warn: "warning" }; const facts = [ command === "" ? "**Output**" : command.includes("`") ? `\`\` $ ${command} \`\`` : `\`$ ${command}\``, finite(exit) ? `${exit === 0 ? TONE_DOTS.good : TONE_DOTS.bad} exit ${exit}` : "", `${lines.length} ${lines.length === 1 ? "line" : "lines"}`, ...LOG_LEVELS.filter((level) => Object.hasOwn(nouns, level) && counts[level] > 0).map( (level) => `${counts[level]} ${nouns[level]}${counts[level] === 1 || level === "fatal" ? "" : "s"}`, ), ...context.map(([key, text]) => `${key} ${text}`), utc ? "times UTC" : "", ].filter((fact) => fact !== ""); if (lines.length === 0) return paragraphs([facts.join(" Β· "), "_No output._"]); const earlier = Math.max(0, lines.length - LOG_TAIL); const tail = foldRepeats(lines, lines.slice(earlier).map((_, offset) => earlier + offset)).map( (row) => `${clip(lines[row.index].text)}${row.count > 1 ? ` (Γ— ${row.count})` : ""}`, ); const error = firstError(lines); return paragraphs([ facts.join(" Β· "), earlier > 0 ? `_… ${earlier} earlier ${earlier === 1 ? "line" : "lines"}_` : "", fence(tail.join("\n"), "text"), error !== -1 && error < earlier ? `First error, line ${lines[error].number}: \`${clip(lines[error].text).replace(/`/g, "'")}\`` : "", ]); } // --------------------------------------------------------------------------- // Pipeline and Dependencies const PIPELINE_DOTS: Record = { failure: "πŸ”΄", in_progress: "🟑", queued: "⏳", cancelled: "⚫", success: "🟒", neutral: "βšͺ", skipped: "βšͺ", }; /** Jobs a stage lists before "… and N more"; failed and running jobs are always listed. */ const PIPELINE_STAGE_JOBS = 15; /** `label` linked to `url` where it is a web link, else as text. */ function maybeLink(label: string, url: string | null): string { const parsed = url === null ? null : webUrl(url, ["https:", "http:"]); return parsed === null ? escapeProse(label) : link(label, parsed); } /** `- πŸ”΄ [job](url) β€” 5m 53s β€” failed at step 14 "Test build" (1m 25s)`, its message below. */ function pipelineJobLine(job: PipelineJob, label: string): string { const time = job.status === "in_progress" ? (job.ms === null ? "running" : `running ${formatElapsed(job.ms)}`) : job.ms === null ? "" : formatElapsed(job.ms); const step = job.failedStep < 0 ? null : job.steps[job.failedStep]; const running = job.steps.find((candidate) => candidate.status === "in_progress"); const where = step !== null ? `failed at ${step.number === null ? "" : `step ${step.number} `}"${step.name}"${step.ms === null ? "" : ` (${formatElapsed(step.ms)})`}` : running !== undefined ? `at "${running.name}"` : ""; const parts = [`- ${PIPELINE_DOTS[job.status]} ${maybeLink(label, job.url)}`, job.detail ?? "", time, where].filter((part) => part !== ""); const message = job.message ?? step?.message ?? null; return `${parts.join(" β€” ")}${message === null ? "" : `\n ${escapeProse(message.split("\n")[0])}`}`; } /** A CI run: its state, branch, commit and time, then its jobs by stage (or a PR's checks by workflow) with the failing step. */ function pipelineMarkdown(value: Value | undefined): string { const read = readPipeline(value); if (!read.ok) return `_(${read.error})_`; const run = read.run; const title = run.title ?? run.name ?? (run.source === "checks" ? "Checks" : "Pipeline"); const sha = run.sha === null ? "" : `\`${run.sha.slice(0, 7)}\``; const facts = [ `${PIPELINE_DOTS[run.status]} ${STATUS_LABEL[run.status]}${run.detail === null ? "" : ` (${run.detail})`}`, run.title !== null && run.name !== null ? escapeProse(run.name) : "", run.branch === null ? sha : `\`${run.branch}\`${sha === "" ? "" : ` @ ${sha}`}`, run.event?.replace(/_/g, " ") ?? "", run.ms === null ? "" : formatElapsed(run.ms), ].filter((part) => part !== ""); const noun = run.source === "checks" ? "check" : "job"; const header = `**${maybeLink(title, run.url)}** β€” ${facts.join(" Β· ")}`; if (run.jobCount === 0) return `${header}\n\nNo ${noun}s.`; const counts = `${run.jobCount} ${noun}${run.jobCount === 1 ? "" : "s"}: ${jobCountsText(run.counts, " Β· ")}`; const many = run.stages.length > 1; const stages = run.stages.map((stage, index) => { const self = stage.jobs.length === 1 && stage.jobs[0].name === stage.name; const matrix = stage.name === null ? matrixPrefix(stage.jobs.map((job) => job.name)) : null; const label = self ? null : (stage.name ?? matrix?.label ?? (many ? `Stage ${index + 1}` : null)); // Jobs arrive failures first; the rest are cut past the page. const pressing = stage.jobs.filter((job) => job.status === "failure" || job.status === "in_progress").length; const shown = stage.jobs.slice(0, Math.max(PIPELINE_STAGE_JOBS, pressing)); const lines = shown.map((job) => pipelineJobLine(job, job.name.slice(matrix?.length ?? 0))); const rest = stage.jobs.length - shown.length; if (rest > 0) lines.push(`- … and ${rest} more ${noun}${rest === 1 ? "" : "s"}`); const meta = [`${stage.jobs.length} ${noun}${stage.jobs.length === 1 ? "" : "s"}`, stage.ms === null || stage.ms === 0 ? "" : formatElapsed(stage.ms)].filter((part) => part !== ""); return label === null ? lines.join("\n") : `${PIPELINE_DOTS[stage.status]} **${escapeProse(label)}** (${meta.join(" Β· ")}):\n${lines.join("\n")}`; }); return paragraphs([`${header}\n${counts}`, ...stages]); } const DEPENDENCY_DOTS: Record = { critical: "πŸ”΄", high: "πŸ”΄", moderate: "🟠", low: "βšͺ", info: "βšͺ" }; /** Vulnerable packages, and outdated packages per group, a Dependencies rendering lists. */ const DEPENDENCY_ROWS = 25; const DEPENDENCY_SOURCE: Record = { npm: "npm outdated", pnpm: "pnpm outdated", pip: "pip list --outdated" }; /** `to` with the part that changed from `from` in bold: 4.**18.1**. */ function changedVersion(from: string, to: string): string { const [same, changed] = splitChange(from, to); return changed === "" ? same : `${same}**${changed}**`; } function vulnerableLine(item: VulnerablePackage): string { const reach = item.direct === true ? "direct" : item.pulledInBy.length > 0 ? `via ${item.pulledInBy.join(", ")}` : item.direct === false ? "transitive" : ""; const first = item.advisories[0]; const advisory = first === undefined ? item.through.length > 0 ? `through ${item.through.join(", ")}` : "" : `${maybeLink(first.title, first.url)}${item.advisories.length > 1 ? ` (+${item.advisories.length - 1} more)` : ""}`; const target = item.fix === null || item.fix.name === null ? "" : ` ${item.fix.name}${item.fix.version === null ? "" : ` ${item.fix.version}`}`; const fix = item.fix === null ? "no fix yet" : `fix:${target === "" ? " available" : target}${item.fix.major ? " (semver-major)" : ""}`; const head = `- ${DEPENDENCY_DOTS[item.severity]} **${item.severity}** \`${item.name}\`${item.range === null ? "" : ` ${item.range}`}`; return [head, reach, advisory, fix].filter((part) => part !== "").join(" β€” "); } function outdatedLine(item: OutdatedPackage): string { const tags = [ item.type === "dev" || item.type === "optional" || item.type === "peer" ? item.type : "", item.deprecated ? "deprecated" : "", item.breaking ? "0.x: may break" : "", item.severity ?? "", ].filter((tag) => tag !== ""); const suffix = `${tags.length === 0 ? "" : ` (${tags.join(", ")})`}${item.note === null ? "" : ` β€” ${escapeProse(item.note)}`}`; if (item.current === null) { const versions = [item.wanted === null ? "" : `wants ${item.wanted}`, item.latest === null || item.latest === item.wanted ? "" : `latest ${item.latest}`].filter((part) => part !== ""); return `- \`${item.name}\` β€” not installed${versions.length === 0 ? "" : ` (${versions.join(", ")})`}${suffix}`; } const wanted = item.wanted !== null && item.wanted !== item.current && item.wanted !== item.latest ? item.wanted : null; const steps = [item.current]; if (wanted !== null) steps.push(`${changedVersion(item.current, wanted)} (wanted)`); if (item.latest !== null) steps.push(`${changedVersion(wanted ?? item.current, item.latest)}${item.ahead ? " (older than installed)" : ""}`); return `- \`${item.name}\` ${steps.join(" β†’ ")}${suffix}`; } /** A dependency report: vulnerabilities by severity with their fixes, then outdated packages by semver bump. */ function dependenciesMarkdown(value: Value | undefined): string { const read = readDependencies(value); if (!read.ok) return `_(${read.error})_`; const report = read.report; const vulnerable = DEPENDENCY_SEVERITIES.some((severity) => report.severities[severity] > 0); const parts: string[] = []; if (vulnerable) { const strip = DEPENDENCY_SEVERITIES.filter((severity) => report.severities[severity] > 0) .map((severity) => `${DEPENDENCY_DOTS[severity]} ${report.severities[severity]} ${severity}`) .join(" Β· "); const scanned = report.scanned === null ? "" : ` (${report.scanned} dependencies scanned)`; parts.push(`**Vulnerabilities**${report.auditSource === null ? "" : ` β€” ${report.auditSource}`}: ${strip}${scanned}`); const more = moreLine(Math.min(report.vulnerable.length, DEPENDENCY_ROWS), report.vulnerable.length, "package"); parts.push([...report.vulnerable.slice(0, DEPENDENCY_ROWS).map(vulnerableLine), ...(more === "" ? [] : [more])].join("\n")); } else if (report.auditSource !== null) { parts.push(`**Vulnerabilities** β€” ${report.auditSource}: none found${report.scanned === null ? "" : ` in ${report.scanned} dependencies`}.`); } if (report.outdated.length > 0) { const groups = groupOutdated(report.outdated); const source = report.source === null ? "" : (DEPENDENCY_SOURCE[report.source] ?? ""); const summary = groups.map((group) => `${group.packages.length} ${GROUP_LABEL[group.key].toLowerCase()}`).join(" Β· "); parts.push(`**Outdated**${source === "" ? "" : ` β€” ${source}`}: ${report.outdated.length} ${report.outdated.length === 1 ? "package" : "packages"} (${summary})`); for (const group of groups) { const lines = group.packages.slice(0, DEPENDENCY_ROWS).map(outdatedLine); const more = moreLine(lines.length, group.packages.length, "package"); parts.push([`${GROUP_LABEL[group.key]} (${group.packages.length}):`, ...lines, ...(more === "" ? [] : [more])].join("\n")); } } else if (report.source !== null || !vulnerable) { parts.push(report.auditSource === null ? "**Dependencies** β€” every dependency is on its latest version." : "Every dependency is on its latest version."); } return paragraphs(parts); } /** Plain text with the characters markdown would read as emphasis, code or links escaped. */ function plainMarkdown(text: string): string { return text.replace(/[*_`[\]\\<>]/g, "\\$&"); } /** A before/after row's conditions: what differs, what it varies on purpose, what one side leaves out, then what both share beyond the report's shared conditions. */ function comparisonConditions(row: Comparison, shared: Context): string { const comparability = row.comparability; if (comparability === null) return ""; return [ ...comparability.differing.map((item) => `${item.key} differs: ${item.before} before, ${item.after} after`), ...comparability.varied.map((item) => `${item.key} ${item.before ?? "not recorded"} β†’ ${item.after ?? "not recorded"} (varied on purpose)`), ...comparability.oneSided.map((item) => `${item.key} ${item.before ?? item.after} (${item.before === null ? "after" : "before"} only)`), ...Object.entries(comparability.same) .filter(([key]) => !Object.hasOwn(shared, key)) .map(([key, value]) => `${key} ${value}`), ].join(" Β· "); } /** Every run of an experiment: a summary line, the conditions all runs share, then a table per group with β˜… on each metric's best and failed runs kept. */ function allRunsMarkdown(report: AllRunsReport): string { if (report.runs.length === 0) return "**Benchmark** Β· no runs"; const total = report.runs.length; const summary = [ `**Benchmark** Β· ${total} ${total === 1 ? "run" : "runs"}`, report.counts.ok < total ? `${report.counts.ok} measured` : "", ...unmeasuredCounts(report.runs).map((entry) => `${entry.count} ${entry.word}`), report.varying.length > 0 ? `conditions differ: ${report.varying.join(", ")}` : "", ].filter((part) => part !== ""); const shared = formatConditions(report.shared); const metricHeads = report.metrics.map((metric) => `${metric.label} ${metric.better === "higher" ? "↑" : "↓"}`); const cohorts = groupRuns(report, report.groupBy); let budget = MARKDOWN_ROWS; const sections = cohorts.map((cohort) => { const conditions = cohort.varying; const notes = cohort.runs.some((run) => run.note !== null); const shown = cohort.runs.slice(0, Math.max(0, budget)); budget -= shown.length; const rows = shown.map((run) => [ run.name, ...report.metrics.map((metric) => { if (run.status !== "ok") return runStatusWord(run); if (!Object.hasOwn(run.values, metric.key)) return "β€”"; const value = run.values[metric.key]; const text = perfAmount(value, metric.unit, 4); return cohort.best[metric.key] === value ? `**${text}** β˜…` : text; }), ...(conditions.length === 0 ? [] : [conditions.flatMap((key) => (Object.hasOwn(run.context, key) ? [`${key} ${run.context[key]}`] : [])).join(" Β· ")]), ...(notes ? [run.note ?? ""] : []), ]); const title = cohort.key === null ? "" : `**${cohort.value === null ? `${cohort.key} not recorded` : `${cohort.key}: ${cohort.value}`}** Β· ${cohort.runs.length} ${cohort.runs.length === 1 ? "run" : "runs"}`; return paragraphs([ title, table(["Run", ...metricHeads, ...(conditions.length === 0 ? [] : ["Conditions"]), ...(notes ? ["Note"] : [])], rows), moreLine(shown.length, cohort.runs.length, "run"), ]); }); const unlike = cohorts.some((cohort) => cohort.varying.length > 0 && Object.keys(cohort.best).length > 0); return paragraphs([ summary.join(" Β· "), shared === "" ? "" : `Same conditions for every run: ${shared}`, ...sections, `↑ higher is better Β· ↓ lower is better Β· β˜… best of the measured runs${report.groupBy === null ? "" : ` per ${report.groupBy}`}${unlike ? ", among runs whose conditions differ" : ""}`, ]); } /** One compared image: its label, where it is (an https image inline), its capture facts and note. */ function compareImageLine(image: CompareImage, position: number): string { const remote = remoteImage(image.src, image.label); const facts = image.meta.map(([key, value]) => `${key} ${value}`).join(" Β· "); const parts = [remote ?? `\`${image.src}\``, facts, image.note === null ? "" : escapeProse(image.note)].filter((part) => part !== ""); return `${position + 1}. **${escapeProse(image.label)}**${position === 0 ? " (reference)" : ""} β€” ${parts.join(" β€” ")}`; } /** Compare as its images (the reference first) and each condition mismatch against the reference; the pixel views need BB. */ function compareMarkdown(value: Value | undefined): string { const read = readCompare(value); if (!read.ok) return `_(${read.error})_`; const [reference, ...others] = read.images; if (reference === undefined) return "**Image comparison** Β· no images"; const warnings = others.flatMap((other) => { const warning = conditionsWarning(conditionDifferences(reference, other), reference.label, other.label); return warning === null ? [] : [`⚠️ ${others.length > 1 ? `${escapeProse(other.label)}: ` : ""}${escapeProse(warning)}`]; }); const title = others.length === 0 ? `**Image comparison** Β· only the reference so far` : `**Image comparison** Β· ${escapeProse(reference.label)} vs ${others.map((other) => escapeProse(other.label)).join(", ")}`; return paragraphs([ title, read.images.map(compareImageLine).join("\n"), warnings.join("\n"), read.ignored > 0 ? `_${read.ignored} ${read.ignored === 1 ? "entry" : "entries"} without a src left out_` : "", others.length === 0 ? "" : "_Side by side, wipe, overlay and the pixel difference with its changed regions show in BB._", ]); } /** A value as a code span, its fence longer than any backtick run inside. */ function provenanceCode(value: string): string { const longest = (value.match(/`+/g) ?? []).reduce((max, run) => Math.max(max, run.length), 0); const ticks = "`".repeat(longest + 1); return longest === 0 ? `${ticks}${value}${ticks}` : `${ticks} ${value} ${ticks}`; } const PROVENANCE_MARKS: Readonly> = { done: "βœ…", failed: "❌", running: "πŸ”„", none: "❔", waiting: "⏳", "not-reached": "βšͺ", skipped: "⏭️" }; /** `branch `main` βœ— expected `feat/399``, a URL as a link. */ function provenanceFact(fact: ProvenanceFact, requested: boolean): string { const url = fact.key === "url" ? webUrl(fact.value, ["https:", "http:"]) : null; const value = url === null ? provenanceCode(fact.short) : link(fact.short, url); if (fact.check === null) return `${escapeProse(fact.label)} ${value}${requested && fact.confirmed ? " βœ“" : ""}`; const other = fact.check.kind === "expected" ? `expected ${provenanceCode(shortValue(fact.key, fact.check.expected))}` : `was ${provenanceCode(shortValue(fact.key, fact.check.previous))}`; return `${escapeProse(fact.label)} ${value} βœ— ${other}`; } function provenanceEvidence(evidence: ProvenanceEvidence): string { const label = evidence.label === null ? "" : `${escapeProse(evidence.label)}: `; switch (evidence.kind) { case "url": { const url = webUrl(evidence.url, ["https:", "http:"]); return url === null ? `${label}${provenanceCode(evidence.url)}` : link(evidence.label ?? evidence.url.replace(/^https?:\/\//, ""), url); } case "image": return `${label === "" ? "image: " : label}${provenanceCode(evidence.src)}`; case "file": return `${label}${provenanceCode(evidence.line === null ? evidence.path : `${evidence.path}:${evidence.line}`)}`; case "text": return `${label}${provenanceCode(evidence.text.replace(/\s*\n\s*/g, " "))}`; } } /** A provenance chain: the verdict and what is wrong first, then each stage with its outcome, facts (wrong ones with both values) and evidence. */ function provenanceMarkdown(stages: Value | undefined, expected: Value | undefined): string { const read = readProvenance(stages, expected); if (!read.ok) return `_(${read.error})_`; const chain = read.provenance; if (chain.stages.length === 0) return "**Provenance** Β· no stages yet"; const { verdict } = chain; const requested = new Set(chain.expected.map((fact) => fact.key)); const head = [`${TONE_DOTS[verdict.tone]} **${escapeProse(verdict.title)}**`, ...verdict.lines.map((line) => `- ${escapeProse(line.text)}`)].join("\n"); const wanted = chain.expected.length === 0 ? "" : ` Β· requested: ${chain.expected .map((fact) => { const wrong = chain.mismatches.some((mismatch) => mismatch.key === fact.key && mismatch.check.kind === "expected"); return `${escapeProse(fact.label)} ${provenanceCode(fact.short)} ${wrong ? "βœ—" : fact.confirmed ? "βœ“" : "(not confirmed)"}`; }) .join(", ")}`; const lines = chain.stages.map((stage, index) => { const wrong = stage.facts.some((fact) => fact.check !== null); const mark = stage.receipt === "receipt" ? (stage.status === "done" && wrong ? "⚠️" : PROVENANCE_MARKS[stage.status]) : PROVENANCE_MARKS[stage.receipt]; const state = stage.receipt === "receipt" ? (stage.status === "done" ? "" : STAGE_STATUS_LABEL[stage.status].toLowerCase()) : RECEIPT_LABEL[stage.receipt]; const meta = [state, stage.note ?? "", stage.ms === null ? "" : formatElapsed(stage.ms), stage.last ? "last receipt" : ""].filter((part) => part !== ""); const out = [`${index + 1}. ${mark} **${escapeProse(stage.name)}**${meta.length === 0 ? "" : ` β€” ${meta.map(escapeProse).join(" Β· ")}`}`]; if (stage.facts.length > 0) out.push(` ${stage.facts.map((fact) => provenanceFact(fact, requested.has(fact.key))).join(" Β· ")}`); if (stage.detail !== null) out.push(` ${escapeProse(stage.detail.replace(/\s*\n\s*/g, " "))}`); if (stage.evidence.length > 0) out.push(` Evidence: ${stage.evidence.map(provenanceEvidence).join(" Β· ")}`); return out.join("\n"); }); return paragraphs([head, `${escapeProse(chainSummary(chain))}${wanted}`, lines.join("\n")]); } /** A check as one glyph: checked results filled, a claim πŸ’¬, nothing run βšͺ, n/a βž–. */ function acceptanceMark(check: Check): string { if (check.notApplicable) return "βž–"; return { passed: "βœ…", failed: "❌", blocked: "β›”", untested: "βšͺ", claimed: "πŸ’¬", skipped: "⏭️" }[check.status]; } /** Evidence inline: a file as `path:line`, a web link, an image by its path, the first line of a tool's text. */ function acceptanceEvidence(item: AcceptanceEvidence): string { const label = item.label === null ? "" : `${escapeProse(item.label)}: `; if (item.kind === "file") return `${label}\`${item.path}${item.line === null ? "" : `:${item.line}${item.endLine === null ? "" : `-${item.endLine}`}`}\``; if (item.kind === "text") { const first = item.text.split("\n")[0]!.trim(); return `${label}β€œ${escapeProse(first.length > 120 ? `${first.slice(0, 119)}…` : first)}”`; } const href = item.kind === "url" ? item.url : item.src; const url = webUrl(href, ["https:", "http:"]); return url === null ? `${label}\`${href}\`` : link(item.label ?? (item.kind === "image" ? "image" : url.host + url.pathname.replace(/\/$/, "")), url); } /** A check's detail lines under its list item: the note, method, run and time, and its evidence. */ function acceptanceDetail(check: Check): string[] { const facts = [check.method, check.run, check.at].filter((part) => part !== null); return [ check.note === null ? "" : ` ${escapeProse(check.note.replace(/\s*\n\s*/g, " "))}`, facts.length === 0 ? "" : ` _${facts.map(escapeProse).join(" Β· ")}_`, check.evidence.length === 0 ? "" : ` Evidence: ${check.evidence.map(acceptanceEvidence).join(" Β· ")}`, ].filter((part) => part !== ""); } /** * Acceptance as text: the verdict first, what needs the user, the owner's * limitations, then a matrix as a table of marks with every gap listed under * it, or one line per criterion with its note and evidence. */ function acceptanceMarkdown(criteria: Value | undefined, columns: Value | undefined): string { const read = readAcceptance(criteria, columns); if (!read.ok) return `_(${read.error})_`; const report = read.report; const verdict = acceptanceVerdict(report); const title = `**${escapeProse(report.title ?? "Acceptance")}**`; if (report.criteria.length === 0) return `${title} Β· no criteria yet`; const more = report.criteria.length > MARKDOWN_ROWS ? `_… and ${report.criteria.length - MARKDOWN_ROWS} more criteria_` : ""; const contradiction = ownerContradiction(report, verdict); const cells = cellsLine(verdict); const head = [ [ title, `${report.criteria.length} ${report.criteria.length === 1 ? "criterion" : "criteria"}`, verdict.optional.total > 0 ? `${verdict.optional.total} optional` : "", report.columns.length > 0 ? `${report.columns.length} conditions` : "", report.hiddenColumns > 0 ? `${report.hiddenColumns} more not shown` : "", ] .filter((part) => part !== "") .join(" Β· "), `**${verdict.headline}**: ${[verdict.proven, ...verdict.parts].join(" Β· ")}`, cells === null ? "" : `_${cells}_`, contradiction === null ? "" : `⚠️ ${contradiction}`, report.statedVerdict === null ? "" : `Stated verdict: β€œ${escapeProse(report.statedVerdict)}”`, ].filter((part) => part !== ""); const needs = verdict.needsYou.length === 0 ? "" : ["**Needs you**", ...verdict.needsYou.map((item) => `- ${escapeProse(item.what || "Your input")} β€” ${escapeProse(needsPlaces(item))}`)].join("\n"); const limitations = report.limitations.length === 0 ? "" : ["Limitations the owner stated:", ...report.limitations.map((item) => `- ${escapeProse(item)}`)].join("\n"); const shown = report.criteria.slice(0, MARKDOWN_ROWS); if (report.columns.length === 0) { const lines = shown.map((criterion) => { const check = criterion.own; const optional = criterion.required ? "" : " _(optional)_"; return [`- ${acceptanceMark(check)} ${escapeProse(criterion.name)}${optional} β€” ${escapeProse(checkLabel(check))}`, ...acceptanceDetail(check)].join("\n"); }); return paragraphs([head.join("\n"), needs, limitations, [lines.join("\n"), more].filter((part) => part !== "").join("\n")]); } const rows = shown.map((criterion) => [ `${acceptanceMark(criterion.own)} ${criterion.name}${criterion.required ? "" : " (optional)"}`, ...criterion.cells!.map((check) => acceptanceMark(check)), ]); const marks = new Set(shown.flatMap((criterion) => [criterion.own, ...criterion.cells!].map(acceptanceMark))); const legend = Object.entries({ "βœ…": "passed", "❌": "failed", "β›”": "blocked", "βšͺ": "not tested", "πŸ’¬": "only claimed", "⏭️": "skipped", "βž–": "not applicable" }) .filter(([mark]) => marks.has(mark)) .map(([mark, word]) => `${mark} ${word}`) .join(" Β· "); // Each open criterion's own note (when it has one), then its open cells; only cells are counted. let gapCells = 0; const gaps = shown.flatMap((criterion) => { if (!isGap(criterion)) return []; const own = acceptanceDetail({ ...criterion.own, method: null, run: null, at: null }); const row = own.length === 0 ? [] : [[`- ${acceptanceMark(criterion.own)} **${escapeProse(criterion.name)}**${criterion.own.by === null ? "" : ` (${escapeProse(criterion.own.by)})`}`, ...own].join("\n")]; const cells = criterion.cells!.flatMap((check, position) => { if (!isCellGap(check)) return []; const where = `${escapeProse(criterion.name)} Β· ${escapeProse(report.columns[position] ?? "")}`; return [[`- ${acceptanceMark(check)} ${where} β€” ${escapeProse(checkLabel(check))}`, ...acceptanceDetail(check)].join("\n")]; }); gapCells += cells.length; return [...row, ...cells]; }); const gapList = gaps.slice(0, MARKDOWN_ROWS); return paragraphs([ head.join("\n"), needs, limitations, [table(["Criterion", ...report.columns], rows), more].filter((part) => part !== "").join("\n"), `_${legend}_`, gapList.length === 0 ? "" : [`**Gaps** (${gapCells} ${gapCells === 1 ? "cell" : "cells"})`, ...gapList, moreLine(gapList.length, gaps.length, "gap")].filter((part) => part !== "").join("\n"), ]); } /** Words of a lone transcript shown before "…". */ const TRANSCRIPT_EXCERPT_WORDS = 80; /** Transcripts as WER per hypothesis, then each error with its time; a lone transcript as its text. */ function transcriptMarkdown(value: Value | undefined, audio: string): string { const read = readTracks(value); if (!read.ok) return `_(${read.error})_`; const analysis = analyse(read.tracks); if (analysis === null) return "**Transcript** Β· no words"; const { reference, refTokens, comparisons, regions } = analysis; const end = Math.max(0, ...read.tracks.flatMap((track) => track.words.map((word) => word.end ?? 0))); const facts = [`${refTokens.length} ${refTokens.length === 1 ? "word" : "words"}`, end > 0 ? formatClock(end, false) : ""].filter((part) => part !== ""); const recording = audio === "" ? "" : `Recording: \`${audio}\``; if (comparisons.length === 0) { const words = reference.words.slice(0, TRANSCRIPT_EXCERPT_WORDS).map((word) => word.text); return paragraphs([ [`**Transcript** Β· ${reference.name}`, ...facts].join(" Β· "), `> ${words.join(" ")}${reference.words.length > words.length ? " …" : ""}`, recording, ]); } const score = (index: number) => { const comparison = comparisons[index]; return `WER ${comparison.wer === null ? "β€”" : formatWer(comparison.wer)} (${countsText(comparison.counts)})`; }; const head = comparisons.length === 1 ? `**Transcript** Β· ${read.tracks[1].name} against ${reference.name}: ${score(0)} Β· ${facts.join(" Β· ")}` : [ [`**Transcript** Β· ${comparisons.length} transcripts against ${reference.name}`, ...facts].join(" Β· "), ...comparisons.map((comparison, index) => `- ${read.tracks[comparison.track].name}: ${score(index)}`), ].join("\n"); const shown = regions.slice(0, MARKDOWN_ROWS); const lines = shown.map((region) => { const at = region.start === null ? "" : `${formatClock(region.start)} `; const who = comparisons.length > 1 ? `${read.tracks[region.track].name}: ` : ""; return `- ${at}${who}${describeRegion(region)}`; }); return paragraphs([head, lines.length === 0 ? "" : [...lines, moreLine(shown.length, regions.length, "error")].filter((part) => part !== "").join("\n"), recording]); }