|
| 1 | +import type { ChangeRecord } from 'solid-js/attribution'; |
| 2 | +import type { TimelineEntry, TimelineRun } from '../timeline/tracker.js'; |
| 3 | +import { code } from './markdown.js'; |
| 4 | +import { isSensitiveName, REDACTED, redactText, redactUrl } from './redact.js'; |
| 5 | + |
| 6 | +export interface TimelineReportInput { |
| 7 | + entry: TimelineEntry; |
| 8 | + /** The path and query of the page. */ |
| 9 | + route: string; |
| 10 | +} |
| 11 | + |
| 12 | +/** Most re-runs the report lists. The rest are counted. */ |
| 13 | +const MAX_REPORT_RUNS = 50; |
| 14 | + |
| 15 | +/** |
| 16 | + * A duration for reading. Browsers round the clock to 0.1ms or coarser, so a |
| 17 | + * shorter run reads as under that instead of as zero. |
| 18 | + */ |
| 19 | +export function ms(value: number | undefined): string { |
| 20 | + if (value === undefined) return '?'; |
| 21 | + if (value < 0.1) return '<0.1ms'; |
| 22 | + return value < 1 ? `${value.toFixed(2)}ms` : `${value.toFixed(1)}ms`; |
| 23 | +} |
| 24 | + |
| 25 | +export function plural(count: number, word: string): string { |
| 26 | + return `${count} ${word}${count === 1 ? '' : 's'}`; |
| 27 | +} |
| 28 | + |
| 29 | +/** `count` 0 → 1, with the values hidden when the name looks sensitive. */ |
| 30 | +export function changeText(change: ChangeRecord): string { |
| 31 | + const name = code(change.name); |
| 32 | + if (change.kind !== 'write') return `${change.kind} ${name}`; |
| 33 | + if (change.value === undefined) return `write ${name}`; |
| 34 | + if (isSensitiveName(change.name)) return `write ${name} ${REDACTED}`; |
| 35 | + const prev = change.prev === undefined ? '' : `${redactText(change.prev)} → `; |
| 36 | + return `write ${name} ${prev}${redactText(change.value)}`; |
| 37 | +} |
| 38 | + |
| 39 | +/** The changes that made a run happen, nearest first, each with what caused it. */ |
| 40 | +export function causeLines(causes: ChangeRecord[], depth = 0): string[] { |
| 41 | + const out: string[] = []; |
| 42 | + for (const cause of causes) { |
| 43 | + const text = cause.kind === 'derived' ? `${code(cause.name)} changed` : changeText(cause); |
| 44 | + out.push(`${' '.repeat(depth)}- ← ${text}`); |
| 45 | + if (cause.causes?.length) out.push(...causeLines(cause.causes, depth + 1)); |
| 46 | + } |
| 47 | + return out; |
| 48 | +} |
| 49 | + |
| 50 | +function runLine(run: TimelineRun): string { |
| 51 | + const { event } = run; |
| 52 | + const notes: string[] = [ms(event.selfMs)]; |
| 53 | + if (run.effectMs !== undefined) notes.push(`callback ${ms(run.effectMs)}`); |
| 54 | + if (!event.changed) notes.push('no change'); |
| 55 | + if (event.phase !== 'plain') notes.push(event.phase); |
| 56 | + if (event.depsAdded.length) notes.push(`now reads ${event.depsAdded.map(code).join(', ')}`); |
| 57 | + if (event.depsRemoved.length) |
| 58 | + notes.push(`stopped reading ${event.depsRemoved.map(code).join(', ')}`); |
| 59 | + return `- ${event.nodeKind} ${code(event.nodeName)} (${notes.join(', ')})`; |
| 60 | +} |
| 61 | + |
| 62 | +/** A Markdown report of what one action made the app do, for an agent to read. */ |
| 63 | +export function timelineReport(input: TimelineReportInput): string { |
| 64 | + const { entry } = input; |
| 65 | + const { interaction } = entry; |
| 66 | + const out: string[] = [`# Solid update: ${code(entry.label)}`, '']; |
| 67 | + |
| 68 | + out.push(`- Page: ${code(redactUrl(input.route))}`); |
| 69 | + if (interaction) { |
| 70 | + out.push(`- Outcome: ${interaction.outcome ?? 'pending'}`); |
| 71 | + if (interaction.inputDelayMs !== undefined) { |
| 72 | + out.push(`- Input delay: ${ms(interaction.inputDelayMs)}`); |
| 73 | + } |
| 74 | + out.push(`- Handler: ${ms(interaction.handlerMs)}`); |
| 75 | + if (interaction.continuationMs !== undefined) { |
| 76 | + out.push(`- Async handler continued for ${ms(interaction.continuationMs)}`); |
| 77 | + } |
| 78 | + out.push(`- Re-runs: ${interaction.runs}, ${ms(interaction.runMs)} in total`); |
| 79 | + if (interaction.created) out.push(`- Computations created: ${interaction.created}`); |
| 80 | + if (interaction.settledMs !== undefined) { |
| 81 | + out.push(`- Settled: ${ms(interaction.settledMs)} after the event`); |
| 82 | + } |
| 83 | + } else { |
| 84 | + out.push(`- Re-runs: ${entry.runs.length + entry.droppedRuns}`); |
| 85 | + } |
| 86 | + if (entry.flushes) out.push(`- Flushes: ${entry.flushes}, ${ms(entry.flushMs)}`); |
| 87 | + |
| 88 | + if (entry.writes.length) { |
| 89 | + out.push('', '## Writes', ''); |
| 90 | + for (const write of entry.writes) out.push(`- ${changeText(write)}`); |
| 91 | + } |
| 92 | + |
| 93 | + if (entry.runs.length) { |
| 94 | + out.push('', '## Re-runs, in order', ''); |
| 95 | + for (const run of entry.runs.slice(0, MAX_REPORT_RUNS)) { |
| 96 | + out.push(runLine(run)); |
| 97 | + out.push(...causeLines(run.event.causes, 1)); |
| 98 | + } |
| 99 | + const rest = entry.runs.length - MAX_REPORT_RUNS + entry.droppedRuns; |
| 100 | + if (rest > 0) out.push(`- … ${rest} more re-runs`); |
| 101 | + } |
| 102 | + |
| 103 | + if (entry.calls.length) { |
| 104 | + out.push('', '## Server calls', ''); |
| 105 | + for (const { event } of entry.calls) { |
| 106 | + const status = event.status === undefined ? 'no response' : String(event.status); |
| 107 | + const outcome = event.outcome === 'ok' ? '' : ', failed'; |
| 108 | + out.push( |
| 109 | + `- ${event.method} ${code(event.name ?? event.id)} → ${status} in ${ms(event.durationMs)}${outcome}`, |
| 110 | + ); |
| 111 | + } |
| 112 | + } |
| 113 | + |
| 114 | + if (entry.holds.length) { |
| 115 | + out.push('', '## Holds', ''); |
| 116 | + for (const hold of entry.holds) { |
| 117 | + const blockers = hold.blockers.length |
| 118 | + ? `, waiting on ${hold.blockers.map(code).join(', ')}` |
| 119 | + : ''; |
| 120 | + const silent = hold.acknowledgements.length ? '' : ', with no pending state shown'; |
| 121 | + out.push(`- ${ms(hold.holdMs)}${blockers}${silent}`); |
| 122 | + } |
| 123 | + } |
| 124 | + |
| 125 | + if (entry.navigations.length) { |
| 126 | + out.push('', '## Navigations', ''); |
| 127 | + for (const navigation of entry.navigations) { |
| 128 | + const route = navigation.name ? `${code(navigation.name)} ` : ''; |
| 129 | + out.push(`- ${route}to ${code(navigation.to ?? '?')}, ${navigation.outcome ?? 'pending'}`); |
| 130 | + } |
| 131 | + } |
| 132 | + |
| 133 | + return out.join('\n'); |
| 134 | +} |
0 commit comments