|
| 1 | +import { concernOf, type AsyncRecord } from '../async/tracker.js'; |
| 2 | +import type { ServerFunctionInstance } from '../functions/index.js'; |
| 3 | +import { issueText, type IssueEntry } from '../issues/tracker.js'; |
| 4 | +import type { TimelineEntry } from '../timeline/tracker.js'; |
| 5 | +import { asyncDuration, asyncOrigin, asyncTitle } from './async-report.js'; |
| 6 | +import { errorReport, type ReportFrame } from './error-report.js'; |
| 7 | +import { code } from './markdown.js'; |
| 8 | +import { redactText, redactUrl } from './redact.js'; |
| 9 | +import { ms, plural } from './timeline-report.js'; |
| 10 | + |
| 11 | +/** Errors the session report gives in full, newest first. The rest are counted. */ |
| 12 | +export const SESSION_ERRORS = 3; |
| 13 | +/** Issues the session report lists. */ |
| 14 | +export const SESSION_ISSUES = 20; |
| 15 | +/** Timeline actions the session report lists, newest first. */ |
| 16 | +export const SESSION_ACTIONS = 5; |
| 17 | +/** Flagged async records the session report lists. */ |
| 18 | +export const SESSION_ASYNC = 10; |
| 19 | + |
| 20 | +export interface SessionError { |
| 21 | + error: unknown; |
| 22 | + frames: ReportFrame[]; |
| 23 | +} |
| 24 | + |
| 25 | +export interface SessionReportInput { |
| 26 | + /** Newest first, as the error panel keeps them. */ |
| 27 | + errors: SessionError[]; |
| 28 | + /** How many errors there are in all, which can be more than `errors` holds. */ |
| 29 | + errorCount: number; |
| 30 | + issues: IssueEntry[]; |
| 31 | + timeline: TimelineEntry[]; |
| 32 | + asyncRecords: AsyncRecord[]; |
| 33 | + calls: ServerFunctionInstance[]; |
| 34 | + /** The path and query of the page. */ |
| 35 | + route: string; |
| 36 | + /** The devtools version, so a reader knows what made the report. */ |
| 37 | + version: string; |
| 38 | +} |
| 39 | + |
| 40 | +/** |
| 41 | + * Puts a report one heading level lower, so it reads as a section of another |
| 42 | + * report. Lines inside code blocks are left alone. |
| 43 | + */ |
| 44 | +export function demote(markdown: string): string { |
| 45 | + let fence: string | undefined; |
| 46 | + return markdown |
| 47 | + .split('\n') |
| 48 | + .map((line) => { |
| 49 | + const marks = line.match(/^(`{3,})/)?.[1]; |
| 50 | + if (marks && (fence === undefined || marks.length >= fence.length)) { |
| 51 | + fence = fence === undefined ? marks : undefined; |
| 52 | + return line; |
| 53 | + } |
| 54 | + return fence === undefined && line.startsWith('#') ? `#${line}` : line; |
| 55 | + }) |
| 56 | + .join('\n'); |
| 57 | +} |
| 58 | + |
| 59 | +function failedCall(instance: ServerFunctionInstance): string | undefined { |
| 60 | + const { request, response } = instance; |
| 61 | + const name = code(request.meta?.name ?? request.id); |
| 62 | + if (response && !response.source.ok) { |
| 63 | + return `- ${request.source.method} ${name} → ${response.source.status}`; |
| 64 | + } |
| 65 | + const error = request.meta?.error; |
| 66 | + if (!response && error !== undefined) { |
| 67 | + const message = error instanceof Error ? error.message : String(error); |
| 68 | + return `- ${request.source.method} ${name} → no response: ${redactText(message)}`; |
| 69 | + } |
| 70 | + return undefined; |
| 71 | +} |
| 72 | + |
| 73 | +function actionLine(entry: TimelineEntry): string { |
| 74 | + const parts = [ |
| 75 | + plural(entry.writes.length, 'write'), |
| 76 | + plural(entry.interaction?.runs ?? entry.runs.length + entry.droppedRuns, 're-run'), |
| 77 | + ]; |
| 78 | + if (entry.calls.length) parts.push(plural(entry.calls.length, 'call')); |
| 79 | + const time = entry.interaction?.settledMs ?? entry.flushMs; |
| 80 | + const outcome = entry.interaction?.outcome ? `, ${entry.interaction.outcome}` : ''; |
| 81 | + const writes = entry.writes.length |
| 82 | + ? `: ${entry.writes.map((write) => code(write.name)).join(', ')}` |
| 83 | + : ''; |
| 84 | + return `- ${code(entry.label)}, ${parts.join(', ')} in ${ms(time)}${outcome}${writes}`; |
| 85 | +} |
| 86 | + |
| 87 | +/** |
| 88 | + * One Markdown report of everything the devtools noticed, for an agent to |
| 89 | + * read when it is not clear which panel holds the problem. Each panel adds a |
| 90 | + * section only when it has something in it. |
| 91 | + */ |
| 92 | +export function sessionReport(input: SessionReportInput): string { |
| 93 | + const out: string[] = ['# Solid devtools session', '']; |
| 94 | + out.push(`- Page: ${code(redactUrl(input.route))}`); |
| 95 | + out.push(`- Devtools: ${input.version}`); |
| 96 | + |
| 97 | + const failed = input.calls.map(failedCall).filter((line) => line !== undefined); |
| 98 | + const flagged = input.asyncRecords.filter((record) => concernOf(record)); |
| 99 | + const empty = |
| 100 | + !input.errorCount && |
| 101 | + !input.issues.length && |
| 102 | + !input.timeline.length && |
| 103 | + !flagged.length && |
| 104 | + !failed.length; |
| 105 | + if (empty) { |
| 106 | + out.push('', 'Nothing to report: no errors, issues, actions, async concerns or failed calls.'); |
| 107 | + return out.join('\n'); |
| 108 | + } |
| 109 | + |
| 110 | + if (input.errorCount) { |
| 111 | + out.push('', `## Errors (${input.errorCount})`); |
| 112 | + for (const { error, frames } of input.errors.slice(0, SESSION_ERRORS)) { |
| 113 | + out.push('', demote(demote(errorReport({ error, frames, route: input.route })))); |
| 114 | + } |
| 115 | + const rest = input.errorCount - Math.min(input.errors.length, SESSION_ERRORS); |
| 116 | + if (rest > 0) out.push('', `… ${plural(rest, 'older error')} not shown.`); |
| 117 | + } |
| 118 | + |
| 119 | + if (input.issues.length) { |
| 120 | + out.push('', `## Issues (${input.issues.length})`, ''); |
| 121 | + for (const entry of input.issues.slice(0, SESSION_ISSUES)) { |
| 122 | + const { event, count } = entry; |
| 123 | + const times = count > 1 ? ` ×${count}` : ''; |
| 124 | + const owner = event.ownerPath?.length ? ` in ${code(event.ownerPath.join(' > '))}` : ''; |
| 125 | + out.push( |
| 126 | + `- ${event.severity} ${code(event.code)}${times}${owner}: ${redactText(issueText(event))}`, |
| 127 | + ); |
| 128 | + } |
| 129 | + const rest = input.issues.length - SESSION_ISSUES; |
| 130 | + if (rest > 0) out.push(`- … ${plural(rest, 'more issue')}`); |
| 131 | + } |
| 132 | + |
| 133 | + if (input.timeline.length) { |
| 134 | + out.push('', '## Recent actions, newest first', ''); |
| 135 | + for (const entry of input.timeline.slice(0, SESSION_ACTIONS)) out.push(actionLine(entry)); |
| 136 | + } |
| 137 | + |
| 138 | + if (flagged.length) { |
| 139 | + out.push('', `## Async concerns (${flagged.length})`, ''); |
| 140 | + for (const record of flagged.slice(0, SESSION_ASYNC)) { |
| 141 | + const origin = asyncOrigin(record); |
| 142 | + out.push( |
| 143 | + `- ${code(asyncTitle(record))}, ${ms(asyncDuration(record))}: ${concernOf(record)}${origin ? `, started by ${code(origin)}` : ''}`, |
| 144 | + ); |
| 145 | + } |
| 146 | + } |
| 147 | + |
| 148 | + if (failed.length) { |
| 149 | + out.push('', `## Failed server calls (${failed.length})`, ''); |
| 150 | + out.push(...failed); |
| 151 | + } |
| 152 | + |
| 153 | + out.push('', 'Each panel of the devtools has a copy button for the full report of one item.'); |
| 154 | + return out.join('\n'); |
| 155 | +} |
0 commit comments