Line data Source code
1 : /**
2 : * One call site, two sinks: the console (for whoever has devtools open) and
3 : * the panel's ring buffer (for whoever is copying a report).
4 : *
5 : * Before this module the two were wired independently — a handful of
6 : * `recordDevEvent` calls that never printed, and a handful of bare
7 : * `console.warn`s the panel never saw — so the console and the copied report
8 : * disagreed about what happened. New structured wire events use
9 : * {@link crdtLog}; existing document events remain in the shared ring buffer.
10 : */
11 : import type { CrdtLogLevel } from './crdtDebugGate'
12 : import {
13 : isCrdtDebugEnabled,
14 : isCrdtDebugOptedOut,
15 : isLevelEnabled
16 : } from './crdtDebugGate'
17 : import type { CrdtLogScope, DevEventKind } from './devPanelLog'
18 : import { recordDevEvent, sanitizeDevEventDetail } from './devPanelLog'
19 :
20 : /**
21 : * Console tint per scope, so a busy log reads as layers rather than as one
22 : * undifferentiated stream.
23 : */
24 1 : const SCOPE_STYLE: Record<CrdtLogScope, string> = {
25 : wire: 'color:#7dd3fc',
26 : doc: 'color:#a5b4fc'
27 : }
28 :
29 1 : const CONSOLE_METHOD: Record<CrdtLogLevel, 'warn' | 'info' | 'debug'> = {
30 : warn: 'warn',
31 : info: 'info',
32 : debug: 'debug',
33 : trace: 'debug'
34 : }
35 :
36 : interface CrdtLogEntry {
37 : scope: CrdtLogScope
38 : level: CrdtLogLevel
39 : kind: DevEventKind
40 : /** Short human sentence; the `detail` carries the structure. */
41 : message: string
42 : detail?: unknown
43 : }
44 :
45 : /**
46 : * Emit one CRDT-internal event.
47 : *
48 : * The ring buffer records while the debug instrument is enabled even when the
49 : * selected console level is quiet. Ordinary production sessions retain no
50 : * frame or actor details; a tester must opt in before reproducing an issue.
51 : */
52 0 : function crdtLog(entry: CrdtLogEntry): void {
53 0 : const { scope, level, kind, message, detail } = entry
54 0 : const optedOut = isCrdtDebugOptedOut()
55 0 : if (!optedOut) recordDevEvent(kind, detail ?? null, { scope, level })
56 :
57 0 : if (optedOut && level !== 'warn') return
58 0 : if (!isLevelEnabled(level)) return
59 : const line = `%c[crdt:${scope}]%c ${kind} — ${message}`
60 0 : const args: unknown[] = [line, SCOPE_STYLE[scope], '']
61 : // `warn` reaches the console even when the instrument is off, so that a
62 : // fail-closed follower is never silent. The MESSAGE is what earns that
63 : // exemption — dumping document state into an opted-out user's console does
64 : // not. The detail is still in the ring buffer for whoever opted in.
65 0 : if (detail !== undefined && isCrdtDebugEnabled())
66 0 : args.push(sanitizeDevEventDetail(detail))
67 0 : console[CONSOLE_METHOD[level]](...args)
68 : }
69 :
70 : /**
71 : * Bind a scope once so call sites read as `wire.trace('…')` rather than
72 : * repeating the scope on every event.
73 : */
74 1 : function scopedCrdtLog(scope: CrdtLogScope) {
75 1 : const at =
76 : (level: CrdtLogLevel) =>
77 : (kind: DevEventKind, message: string, detail?: unknown): void =>
78 : crdtLog({ scope, level, kind, message, detail })
79 :
80 1 : return {
81 : warn: at('warn'),
82 : info: at('info'),
83 : debug: at('debug'),
84 : trace: at('trace')
85 : }
86 : }
87 :
88 1 : export const wireLog = scopedCrdtLog('wire')
|