@venizia/vulcan 0.4.5 → 0.4.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (54) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/checks/wiki-anchors.ts +8 -0
  4. package/base/checks/wiki-source-links.ts +8 -0
  5. package/base/hooks/guard-git.ts +9 -2
  6. package/base/hooks/guard-writes.ts +4 -0
  7. package/base/hooks/session-start.ts +14 -4
  8. package/base/make/vulcan.mk +12 -1
  9. package/base/references/delegation-brief.md +5 -4
  10. package/base/rules.md +2 -2
  11. package/base/skills/docs-writing/SKILL.md +1 -1
  12. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  13. package/base/skills/knowledge-sync/SKILL.md +1 -1
  14. package/base/skills/plan-a-change/SKILL.md +2 -2
  15. package/base/skills/plan-a-change/evals/evals.json +6 -0
  16. package/base/skills/plan-a-change/references/spec-card.md +1 -0
  17. package/base/skills/report-back/SKILL.md +1 -1
  18. package/base/skills/retro/SKILL.md +1 -1
  19. package/base/skills/review-a-change/SKILL.md +1 -1
  20. package/base/skills/ship/SKILL.md +1 -1
  21. package/base/skills/visualize-work/SKILL.md +33 -11
  22. package/base/skills/visualize-work/references/spec.md +77 -12
  23. package/package.json +4 -4
  24. package/src/config/schema.ts +58 -4
  25. package/src/doctor/checks.ts +29 -1
  26. package/src/doctor/runner.ts +2 -0
  27. package/src/hooks/command-view.ts +24 -0
  28. package/src/hooks/common/constants.ts +10 -0
  29. package/src/hooks/guard-git.ts +78 -2
  30. package/src/hooks/guard-outside.ts +20 -3
  31. package/src/hooks/guard-writes.ts +17 -6
  32. package/src/hooks/index.ts +2 -0
  33. package/src/hooks/project-guards.ts +123 -0
  34. package/src/hooks/project-tmp.ts +36 -0
  35. package/src/hooks/session-digest.ts +5 -0
  36. package/src/manifest/render.ts +38 -0
  37. package/src/sync/claude-launch.ts +48 -0
  38. package/src/sync/index.ts +1 -0
  39. package/src/sync/local-choice.ts +2 -0
  40. package/src/visualize/assets.ts +195 -54
  41. package/src/visualize/charts.ts +235 -0
  42. package/src/visualize/constants.ts +106 -1
  43. package/src/visualize/diagrams.ts +224 -0
  44. package/src/visualize/icons.ts +28 -0
  45. package/src/visualize/layout.ts +58 -8
  46. package/src/visualize/page.ts +152 -146
  47. package/src/visualize/schema.ts +246 -0
  48. package/src/visualize/sections.ts +370 -0
  49. package/src/visualize/validate.ts +100 -7
  50. package/src/wiki/anchors.ts +118 -0
  51. package/src/wiki/command.ts +110 -0
  52. package/src/wiki/constants.ts +30 -0
  53. package/src/wiki/index.ts +4 -0
  54. package/src/wiki/source-links.ts +186 -0
@@ -4,7 +4,9 @@ import {
4
4
  DEFAULT_CHROME,
5
5
  EdgeVariants,
6
6
  EvidenceLabels,
7
+ MinimapStates,
7
8
  NodeKinds,
9
+ NodeStates,
8
10
  StatusStates,
9
11
  VisualizeLimits,
10
12
  } from './constants.ts';
@@ -37,6 +39,8 @@ const HTTPS = z
37
39
  const rows = <T extends z.ZodType>(item: T) =>
38
40
  z.array(item).min(1).max(VisualizeLimits.MAX_ROWS_PER_TABLE);
39
41
 
42
+ const STATE = choice({ set: NodeStates.SCHEME_SET });
43
+
40
44
  const NODE = z.strictObject({
41
45
  id: ID,
42
46
  label: text(VisualizeLimits.MAX_LABEL),
@@ -45,6 +49,7 @@ const NODE = z.strictObject({
45
49
  row: GRID,
46
50
  col: GRID,
47
51
  kind: choice({ set: NodeKinds.SCHEME_SET }).optional(),
52
+ state: STATE.optional(),
48
53
  });
49
54
 
50
55
  const EDGE = z.strictObject({
@@ -77,6 +82,207 @@ const SIDE = (changed: TChangeKind) =>
77
82
  ),
78
83
  });
79
84
 
85
+ const LIST = (max = VisualizeLimits.MAX_LIST) =>
86
+ z.array(text(VisualizeLimits.MAX_SENTENCE)).min(1).max(max);
87
+ const NUMBER = z.number().finite().min(-1_000_000_000).max(1_000_000_000);
88
+
89
+ const COMPARISON = z.strictObject({
90
+ criteria: z.array(text(VisualizeLimits.MAX_LABEL)).min(1).max(VisualizeLimits.MAX_CRITERIA),
91
+ options: z
92
+ .array(
93
+ z.strictObject({
94
+ name: text(VisualizeLimits.MAX_LABEL),
95
+ line: text(VisualizeLimits.MAX_SENTENCE).optional(),
96
+ /** One score from 1 to 5 per criterion, in the order of `criteria`. */
97
+ scores: z.array(z.number().int().min(1).max(5)).min(1).max(VisualizeLimits.MAX_CRITERIA),
98
+ pros: LIST().optional(),
99
+ cons: LIST().optional(),
100
+ recommended: z.boolean().optional(),
101
+ }),
102
+ )
103
+ .min(2)
104
+ .max(VisualizeLimits.MAX_COMPARE_OPTIONS),
105
+ note: text(VisualizeLimits.MAX_SENTENCE).optional(),
106
+ });
107
+
108
+ const IDEA_MAP = z.strictObject({
109
+ center: text(VisualizeLimits.MAX_LABEL),
110
+ branches: z
111
+ .array(
112
+ z.strictObject({
113
+ label: text(VisualizeLimits.MAX_LABEL),
114
+ items: z
115
+ .array(text(VisualizeLimits.MAX_LABEL))
116
+ .min(1)
117
+ .max(VisualizeLimits.MAX_BRANCH_ITEMS),
118
+ note: text(VisualizeLimits.MAX_SENTENCE).optional(),
119
+ }),
120
+ )
121
+ .min(2)
122
+ .max(VisualizeLimits.MAX_BRANCHES),
123
+ });
124
+
125
+ const DIAGRAM = z.discriminatedUnion('type', [
126
+ z.strictObject({
127
+ type: z.literal('row'),
128
+ nodes: z
129
+ .array(
130
+ z.strictObject({
131
+ label: text(VisualizeLimits.MAX_LABEL),
132
+ sub: text(VisualizeLimits.MAX_LABEL).optional(),
133
+ }),
134
+ )
135
+ .min(2)
136
+ .max(5),
137
+ /** Labels of the arrows between consecutive boxes; one fewer than the boxes. */
138
+ arrows: z.array(text(VisualizeLimits.MAX_EDGE_LABEL)).max(4).optional(),
139
+ }),
140
+ z.strictObject({
141
+ type: z.literal('layers'),
142
+ layers: z
143
+ .array(
144
+ z.strictObject({
145
+ label: text(VisualizeLimits.MAX_LABEL),
146
+ items: z.array(text(VisualizeLimits.MAX_LABEL)).min(1).max(5),
147
+ }),
148
+ )
149
+ .min(2)
150
+ .max(VisualizeLimits.MAX_LAYERS),
151
+ }),
152
+ ]);
153
+
154
+ const EXPLAINER = z.strictObject({
155
+ steps: z
156
+ .array(
157
+ z.strictObject({
158
+ title: text(VisualizeLimits.MAX_LABEL),
159
+ text: text(VisualizeLimits.MAX_SENTENCE),
160
+ diagram: DIAGRAM.optional(),
161
+ }),
162
+ )
163
+ .min(1)
164
+ .max(VisualizeLimits.MAX_EXPLAINER_STEPS),
165
+ });
166
+
167
+ const ARCHITECTURE = z.strictObject({
168
+ layers: z
169
+ .array(
170
+ z.strictObject({
171
+ label: text(VisualizeLimits.MAX_LABEL),
172
+ boxes: z
173
+ .array(
174
+ z.strictObject({
175
+ id: ID,
176
+ label: text(VisualizeLimits.MAX_LABEL),
177
+ sub: text(VisualizeLimits.MAX_LABEL).optional(),
178
+ state: STATE.optional(),
179
+ }),
180
+ )
181
+ .min(1)
182
+ .max(VisualizeLimits.MAX_LAYER_BOXES),
183
+ }),
184
+ )
185
+ .min(1)
186
+ .max(VisualizeLimits.MAX_LAYERS),
187
+ links: z
188
+ .array(
189
+ z.strictObject({ from: ID, to: ID, label: text(VisualizeLimits.MAX_EDGE_LABEL).optional() }),
190
+ )
191
+ .max(VisualizeLimits.MAX_LINKS)
192
+ .default([]),
193
+ });
194
+
195
+ const TIMELINE = z.strictObject({
196
+ items: z
197
+ .array(
198
+ z.strictObject({
199
+ date: text(VisualizeLimits.MAX_LABEL),
200
+ title: text(VisualizeLimits.MAX_LABEL),
201
+ text: text(VisualizeLimits.MAX_SENTENCE).optional(),
202
+ state: STATE.optional(),
203
+ }),
204
+ )
205
+ .min(2)
206
+ .max(VisualizeLimits.MAX_TIMELINE),
207
+ });
208
+
209
+ const CHART = z.discriminatedUnion('type', [
210
+ z.strictObject({
211
+ type: z.literal('bar'),
212
+ title: text(VisualizeLimits.MAX_LABEL),
213
+ unit: text(16).optional(),
214
+ labels: z.array(text(VisualizeLimits.MAX_LABEL)).min(2).max(VisualizeLimits.MAX_POINTS),
215
+ /** One value per label, from zero up: a bar starts at the baseline. */
216
+ values: z.array(NUMBER.min(0)).min(2).max(VisualizeLimits.MAX_POINTS),
217
+ }),
218
+ z.strictObject({
219
+ type: z.literal('line'),
220
+ title: text(VisualizeLimits.MAX_LABEL),
221
+ unit: text(16).optional(),
222
+ labels: z.array(text(VisualizeLimits.MAX_LABEL)).min(3).max(VisualizeLimits.MAX_POINTS),
223
+ series: z
224
+ .array(
225
+ z.strictObject({
226
+ name: text(VisualizeLimits.MAX_LABEL),
227
+ values: z.array(NUMBER).min(3).max(VisualizeLimits.MAX_POINTS),
228
+ }),
229
+ )
230
+ .min(1)
231
+ .max(VisualizeLimits.MAX_SERIES),
232
+ }),
233
+ z.strictObject({
234
+ type: z.literal('donut'),
235
+ title: text(VisualizeLimits.MAX_LABEL),
236
+ unit: text(16).optional(),
237
+ parts: z
238
+ .array(
239
+ z.strictObject({
240
+ label: text(VisualizeLimits.MAX_LABEL),
241
+ value: NUMBER.min(0),
242
+ state: STATE.optional(),
243
+ }),
244
+ )
245
+ .min(2)
246
+ .max(VisualizeLimits.MAX_PARTS),
247
+ }),
248
+ ]);
249
+
250
+ const FINDINGS = z.strictObject({
251
+ numbers: z
252
+ .array(
253
+ z.strictObject({
254
+ value: text(16),
255
+ label: text(VisualizeLimits.MAX_LABEL),
256
+ state: STATE.optional(),
257
+ }),
258
+ )
259
+ .min(1)
260
+ .max(VisualizeLimits.MAX_TILES)
261
+ .optional(),
262
+ charts: z.array(CHART).min(1).max(VisualizeLimits.MAX_CHARTS).optional(),
263
+ callouts: z
264
+ .array(z.strictObject({ text: text(VisualizeLimits.MAX_SENTENCE), state: STATE.optional() }))
265
+ .min(1)
266
+ .max(4)
267
+ .optional(),
268
+ });
269
+
270
+ const DECISION_RECORD = z.strictObject({
271
+ context: text(VisualizeLimits.MAX_SENTENCE),
272
+ options: z
273
+ .array(
274
+ z.strictObject({
275
+ name: text(VisualizeLimits.MAX_LABEL),
276
+ summary: text(VisualizeLimits.MAX_SENTENCE),
277
+ chosen: z.boolean().optional(),
278
+ }),
279
+ )
280
+ .min(2)
281
+ .max(5),
282
+ decision: text(VisualizeLimits.MAX_SENTENCE),
283
+ consequences: LIST(),
284
+ });
285
+
80
286
  /** The words of the page, English by default; any of them may be replaced (the owner's language). */
81
287
  const CHROME = z
82
288
  .strictObject({
@@ -93,6 +299,17 @@ const CHROME = z
93
299
  info: text(VisualizeLimits.MAX_LABEL).optional(),
94
300
  })
95
301
  .optional(),
302
+ minimapStates: z
303
+ .strictObject({
304
+ done: text(VisualizeLimits.MAX_LABEL).optional(),
305
+ 'in-progress': text(VisualizeLimits.MAX_LABEL).optional(),
306
+ waiting: text(VisualizeLimits.MAX_LABEL).optional(),
307
+ 'not-started': text(VisualizeLimits.MAX_LABEL).optional(),
308
+ blocked: text(VisualizeLimits.MAX_LABEL).optional(),
309
+ dropped: text(VisualizeLimits.MAX_LABEL).optional(),
310
+ info: text(VisualizeLimits.MAX_LABEL).optional(),
311
+ })
312
+ .optional(),
96
313
  evidenceLabels: z
97
314
  .strictObject({
98
315
  verified: text(VisualizeLimits.MAX_LABEL).optional(),
@@ -132,6 +349,28 @@ export const VISUALIZE_SCHEMA = z.strictObject({
132
349
  next: text(VisualizeLimits.MAX_SENTENCE),
133
350
  })
134
351
  .optional(),
352
+ /** Where each task stands, one row each: the owner's map of the work. */
353
+ minimap: rows(
354
+ z.strictObject({
355
+ task: text(VisualizeLimits.MAX_LABEL),
356
+ status: choice({ set: MinimapStates.SCHEME_SET }),
357
+ note: text(VisualizeLimits.MAX_SENTENCE).optional(),
358
+ }),
359
+ ).optional(),
360
+ /** What the owner has to do, in order: shown as a numbered checklist under `strip.next`. */
361
+ actions: LIST().optional(),
362
+ /** Key numbers; with a `minimap` and no tiles, the page counts the states itself. */
363
+ tiles: z
364
+ .array(
365
+ z.strictObject({
366
+ value: text(16),
367
+ label: text(VisualizeLimits.MAX_LABEL),
368
+ state: STATE.optional(),
369
+ }),
370
+ )
371
+ .min(1)
372
+ .max(VisualizeLimits.MAX_TILES)
373
+ .optional(),
135
374
  flow: z
136
375
  .strictObject({
137
376
  nodes: z.array(NODE).min(1).max(VisualizeLimits.MAX_NODES),
@@ -139,6 +378,13 @@ export const VISUALIZE_SCHEMA = z.strictObject({
139
378
  steps: z.array(STEP).max(VisualizeLimits.MAX_STEPS).default([]),
140
379
  })
141
380
  .optional(),
381
+ architecture: ARCHITECTURE.optional(),
382
+ comparison: COMPARISON.optional(),
383
+ ideaMap: IDEA_MAP.optional(),
384
+ explainer: EXPLAINER.optional(),
385
+ timeline: TIMELINE.optional(),
386
+ findings: FINDINGS.optional(),
387
+ decisionRecord: DECISION_RECORD.optional(),
142
388
  beforeAfter: z
143
389
  .strictObject({ before: SIDE(ChangeKinds.REMOVED), after: SIDE(ChangeKinds.ADDED) })
144
390
  .optional(),
@@ -0,0 +1,370 @@
1
+ import { renderChart, renderTotals, stateIcon, formatNumber } from './charts.ts';
2
+ import { ChangeKinds, MinimapStates, NodeStates } from './constants.ts';
3
+ import type { TChangeKind, TChrome } from './constants.ts';
4
+ import { renderArchitecture, renderDiagram, renderIdeaMap } from './diagrams.ts';
5
+ import type { IDrawing } from './diagrams.ts';
6
+ import { iconSvg } from './icons.ts';
7
+ import { columnsOf, escapeText, figureWidth, renderFigure, renderPathList } from './layout.ts';
8
+ import type { TVisualizeSpec } from './schema.ts';
9
+
10
+ /** What every section needs: the spec, the page's words, and the widths of the figures that must give way to a list on a phone. */
11
+ export interface ISectionContext {
12
+ spec: TVisualizeSpec;
13
+ chrome: TChrome;
14
+ fits: Set<number>;
15
+ }
16
+
17
+ const escaped = (value: string): string => escapeText({ value });
18
+
19
+ /** The word of a state in the page's language. */
20
+ export const stateWord = (opts: { chrome: TChrome; state: string }): string => {
21
+ const key = MinimapStates.keyOf(opts.state) as keyof TChrome['minimapStates'];
22
+
23
+ return opts.chrome.minimapStates[key] ?? opts.state;
24
+ };
25
+
26
+ /** A state as an icon and a word. */
27
+ export const chip = (opts: {
28
+ chrome: TChrome;
29
+ state: string;
30
+ size?: number;
31
+ label?: string;
32
+ }): string =>
33
+ `<span class="chip c-${NodeStates.toneOf(opts.state)}">${stateIcon({ state: opts.state, size: opts.size ?? 16 })}<span>${escaped(opts.label ?? stateWord(opts))}</span></span>`;
34
+
35
+ export const section = (opts: {
36
+ id: string;
37
+ title: string;
38
+ body: string;
39
+ extra?: string;
40
+ }): string =>
41
+ `<section class="sec${opts.extra === undefined ? '' : ` ${opts.extra}`}" id="${opts.id}" data-slide><h2 class="lab">${escaped(opts.title)}</h2>${opts.body}</section>`;
42
+
43
+ /** A drawing in its frame; below the width where its text would pass 12 px the list takes its place. */
44
+ export const figure = (opts: { ctx: ISectionContext; drawing: IDrawing }): string => {
45
+ const width = Math.round(opts.drawing.width);
46
+
47
+ opts.ctx.fits.add(width);
48
+
49
+ return `<div class="fig f${width}">${opts.drawing.svg}</div>${opts.drawing.fallback}`;
50
+ };
51
+
52
+ /** JSON for a `<script type="application/json">`: nothing in it can close the tag or start a comment. */
53
+ export const jsonForScript = (opts: { value: unknown }): string =>
54
+ JSON.stringify(opts.value)
55
+ .replaceAll('<', '\\u003c')
56
+ .replaceAll('>', '\\u003e')
57
+ .replaceAll('&', '\\u0026')
58
+ .replaceAll('
', '\\u2028')
59
+ .replaceAll('
', '\\u2029');
60
+
61
+ export const flowSection = (opts: { ctx: ISectionContext }): string => {
62
+ const { flow } = opts.ctx.spec;
63
+ const { chrome } = opts.ctx;
64
+
65
+ if (flow === undefined) {
66
+ return '';
67
+ }
68
+
69
+ const width = figureWidth({ cols: columnsOf({ flow }) });
70
+ const kinds = [...new Set(flow.nodes.map((node) => node.kind ?? 'step'))];
71
+ const variants = [...new Set(flow.edges.map((edge) => edge.variant ?? 'main'))];
72
+ const states = [
73
+ ...new Set(flow.nodes.flatMap((node) => (node.state === undefined ? [] : [node.state]))),
74
+ ];
75
+ const steps = flow.steps;
76
+ const controls = [
77
+ flow.edges.length > 0
78
+ ? `<button id="play" type="button" aria-pressed="false" data-play="${escaped(chrome.play)}" data-pause="${escaped(chrome.pause)}">${escaped(chrome.play)}</button>`
79
+ : '',
80
+ steps.length > 0
81
+ ? `<button id="prev" type="button">${escaped(chrome.previous)}</button><button id="next" type="button">${escaped(chrome.following)}</button><button id="all" type="button">${escaped(chrome.allSteps)}</button>`
82
+ : '',
83
+ ].join('');
84
+
85
+ opts.ctx.fits.add(width);
86
+
87
+ // The figure, its phone list, then the controls: a sibling order the page CSS relies on to swap the figure for the list.
88
+ return section({
89
+ id: 'flow',
90
+ title: chrome.flow,
91
+ body: `<div class="fig f${width}">${renderFigure({ flow })}</div>${renderPathList({ flow })}<div class="bar">${controls}</div><p id="detail" aria-live="polite">${escaped(chrome.detailHint)}</p>${
92
+ steps.length > 0 ? `<p id="stepnote" aria-live="polite"></p>` : ''
93
+ }<div class="legend">${states.map((state) => chip({ chrome, state })).join('')}${kinds.map((kind) => `<span>${escaped(kind)}</span>`).join('')}${variants.map((variant) => `<span>${escaped(variant)}</span>`).join('')}</div>${
94
+ steps.length > 0
95
+ ? `<ol class="steps-note">${steps.map((step) => `<li><b>${escaped(step.title)}</b> - ${escaped(step.note)}</li>`).join('')}</ol><script type="application/json" id="steps">${jsonForScript({ value: steps })}</script>`
96
+ : ''
97
+ }`,
98
+ });
99
+ };
100
+
101
+ export const architectureSection = (opts: { ctx: ISectionContext }): string => {
102
+ const { architecture } = opts.ctx.spec;
103
+
104
+ if (architecture === undefined) {
105
+ return '';
106
+ }
107
+
108
+ return section({
109
+ id: 'architecture',
110
+ title: opts.ctx.chrome.architecture,
111
+ body: figure({
112
+ ctx: opts.ctx,
113
+ drawing: renderArchitecture({ architecture, chrome: opts.ctx.chrome }),
114
+ }),
115
+ });
116
+ };
117
+
118
+ const dots = (opts: { score: number }): string =>
119
+ `<span class="dots" role="img" aria-label="${opts.score} / 5">${Array.from({ length: 5 }, (_, index) => `<i${index < opts.score ? ' class="on"' : ''}></i>`).join('')}</span>`;
120
+
121
+ export const comparisonSection = (opts: { ctx: ISectionContext }): string => {
122
+ const { comparison } = opts.ctx.spec;
123
+ const { chrome } = opts.ctx;
124
+
125
+ if (comparison === undefined) {
126
+ return '';
127
+ }
128
+
129
+ const totals = comparison.options.map((option) =>
130
+ option.scores.reduce((sum, score) => sum + score, 0),
131
+ );
132
+ const marked = comparison.options.findIndex((option) => option.recommended === true);
133
+ const best = marked === -1 ? totals.indexOf(Math.max(...totals)) : marked;
134
+ const max = comparison.criteria.length * 5;
135
+ const cards = comparison.options
136
+ .map(
137
+ (option, index) =>
138
+ `<article class="opt${option.recommended === true ? ' rec' : ''}">${option.recommended === true ? `<span class="tag">${escaped(chrome.recommended)}</span>` : ''}<h3>${escaped(option.name)}</h3>${option.line === undefined ? '' : `<p class="ln">${escaped(option.line)}</p>`}<p class="tot">${totals[index]}<small> ${escaped(chrome.outOf)} ${max}</small></p><div class="crit">${comparison.criteria.map((criterion, i) => `<div><span>${escaped(criterion)}</span>${dots({ score: option.scores[i] ?? 0 })}</div>`).join('')}</div><ul class="pc">${(option.pros ?? []).map((pro) => `<li class="p">${iconSvg({ name: 'plus', size: 16 })}<span><span class="vh">${escaped(chrome.pros)}: </span>${escaped(pro)}</span></li>`).join('')}${(option.cons ?? []).map((con) => `<li class="c">${iconSvg({ name: 'minus', size: 16 })}<span><span class="vh">${escaped(chrome.cons)}: </span>${escaped(con)}</span></li>`).join('')}</ul></article>`,
139
+ )
140
+ .join('');
141
+
142
+ return section({
143
+ id: 'comparison',
144
+ title: chrome.comparison,
145
+ body: `<div class="card chart"><p class="lab">${escaped(chrome.total)}, ${escaped(chrome.outOf)} ${max}</p>${renderTotals({ names: comparison.options.map((option) => option.name), totals, best, max, chrome })}</div><div class="opts n${comparison.options.length}">${cards}</div>${comparison.note === undefined ? '' : `<p class="note">${iconSvg({ name: 'info', size: 16 })} ${escaped(comparison.note)}</p>`}`,
146
+ });
147
+ };
148
+
149
+ export const ideaMapSection = (opts: { ctx: ISectionContext }): string => {
150
+ const { ideaMap } = opts.ctx.spec;
151
+
152
+ return ideaMap === undefined
153
+ ? ''
154
+ : section({
155
+ id: 'idea-map',
156
+ title: opts.ctx.chrome.ideaMap,
157
+ body: renderIdeaMap({ map: ideaMap }),
158
+ });
159
+ };
160
+
161
+ export const explainerSection = (opts: { ctx: ISectionContext }): string => {
162
+ const { explainer } = opts.ctx.spec;
163
+
164
+ if (explainer === undefined) {
165
+ return '';
166
+ }
167
+
168
+ return section({
169
+ id: 'explainer',
170
+ title: opts.ctx.chrome.explainer,
171
+ body: `<ol class="steps">${explainer.steps
172
+ .map(
173
+ (step, index) =>
174
+ `<li class="estep"><span class="no">${index + 1}</span><div class="sb"><h3>${escaped(step.title)}</h3><p>${escaped(step.text)}</p></div>${step.diagram === undefined ? '' : `<div class="dg">${figure({ ctx: opts.ctx, drawing: renderDiagram({ diagram: step.diagram }) })}</div>`}</li>`,
175
+ )
176
+ .join('')}</ol>`,
177
+ });
178
+ };
179
+
180
+ export const timelineSection = (opts: { ctx: ISectionContext }): string => {
181
+ const { timeline } = opts.ctx.spec;
182
+ const { chrome } = opts.ctx;
183
+
184
+ if (timeline === undefined) {
185
+ return '';
186
+ }
187
+
188
+ return section({
189
+ id: 'timeline',
190
+ title: chrome.timeline,
191
+ body: `<ol class="tl">${timeline.items
192
+ .map(
193
+ (item) =>
194
+ `<li class="c-${item.state === undefined ? 'mut' : NodeStates.toneOf(item.state)}"><span class="dot">${item.state === undefined ? '' : stateIcon({ state: item.state, size: 18 })}</span><time>${escaped(item.date)}</time><h3>${escaped(item.title)}</h3>${item.state === undefined ? '' : `<span class="vh">${escaped(stateWord({ chrome, state: item.state }))}</span>`}${item.text === undefined ? '' : `<p>${escaped(item.text)}</p>`}</li>`,
195
+ )
196
+ .join('')}</ol>`,
197
+ });
198
+ };
199
+
200
+ export const tilesHtml = (opts: {
201
+ tiles: { value: string; label: string; state?: string }[];
202
+ chrome: TChrome;
203
+ }): string =>
204
+ `<ul class="tiles" aria-label="${escaped(opts.chrome.findings)}">${opts.tiles
205
+ .map(
206
+ (tile) =>
207
+ `<li class="tile${tile.state === undefined ? '' : ` c-${NodeStates.toneOf(tile.state)}`}">${tile.state === undefined ? '' : stateIcon({ state: tile.state, size: 22 })}<span class="n">${escaped(tile.value)}</span><span class="l">${escaped(tile.label)}</span>${tile.state === undefined ? '' : `<span class="vh">${escaped(stateWord({ chrome: opts.chrome, state: tile.state }))}</span>`}</li>`,
208
+ )
209
+ .join('')}</ul>`;
210
+
211
+ export const findingsSection = (opts: { ctx: ISectionContext }): string => {
212
+ const { findings } = opts.ctx.spec;
213
+ const { chrome } = opts.ctx;
214
+
215
+ if (findings === undefined) {
216
+ return '';
217
+ }
218
+
219
+ return section({
220
+ id: 'findings',
221
+ title: chrome.findings,
222
+ body: `${findings.numbers === undefined ? '' : tilesHtml({ tiles: findings.numbers, chrome })}${findings.charts === undefined ? '' : `<div class="charts">${findings.charts.map((chart) => renderChart({ chart, chrome })).join('')}</div>`}${findings.callouts === undefined ? '' : `<ul class="callouts">${findings.callouts.map((callout) => `<li class="callout c-${callout.state === undefined ? 'info' : NodeStates.toneOf(callout.state)}">${stateIcon({ state: callout.state ?? 'info', size: 22 })}<p>${callout.state === undefined ? '' : `<span class="vh">${escaped(stateWord({ chrome, state: callout.state }))}: </span>`}${escaped(callout.text)}</p></li>`).join('')}</ul>`}`,
223
+ });
224
+ };
225
+
226
+ export const beforeAfterSection = (opts: { ctx: ISectionContext }): string => {
227
+ const { beforeAfter } = opts.ctx.spec;
228
+ const { chrome } = opts.ctx;
229
+
230
+ if (beforeAfter === undefined) {
231
+ return '';
232
+ }
233
+
234
+ const side = (given: {
235
+ title: string;
236
+ items: { text: string; change?: string }[];
237
+ kind: TChangeKind;
238
+ }): string =>
239
+ `<section><h3>${escaped(given.title)}</h3><ul>${given.items
240
+ .map((item) =>
241
+ item.change === given.kind
242
+ ? `<li class="${given.kind === ChangeKinds.ADDED ? 'add' : 'del'}">${iconSvg({ name: given.kind === ChangeKinds.ADDED ? 'plus' : 'minus', size: 16 })}<span><span class="vh">${escaped(given.kind === ChangeKinds.ADDED ? chrome.added : chrome.removed)}: </span>${escaped(item.text)}</span></li>`
243
+ : `<li class="same">${iconSvg({ name: 'minus', size: 16 })}<span>${escaped(item.text)}</span></li>`,
244
+ )
245
+ .join('')}</ul></section>`;
246
+
247
+ return section({
248
+ id: 'before-after',
249
+ title: `${chrome.before} / ${chrome.after}`,
250
+ body: `<div class="diff">${side({ ...beforeAfter.before, kind: ChangeKinds.REMOVED })}${side({ ...beforeAfter.after, kind: ChangeKinds.ADDED })}</div>`,
251
+ });
252
+ };
253
+
254
+ export const decisionRecordSection = (opts: { ctx: ISectionContext }): string => {
255
+ const { decisionRecord } = opts.ctx.spec;
256
+ const { chrome } = opts.ctx;
257
+
258
+ if (decisionRecord === undefined) {
259
+ return '';
260
+ }
261
+
262
+ return section({
263
+ id: 'decision-record',
264
+ title: chrome.decisionRecord,
265
+ body: `<div class="dr"><p class="lab">${escaped(chrome.context)}</p><p class="ctx">${escaped(decisionRecord.context)}</p><p class="lab">${escaped(chrome.optionsConsidered)}</p><div class="opts n${decisionRecord.options.length}">${decisionRecord.options
266
+ .map(
267
+ (option) =>
268
+ `<article class="opt${option.chosen === true ? ' rec' : ''}">${option.chosen === true ? `<span class="tag">${escaped(chrome.chosen)}</span>` : ''}<h3>${escaped(option.name)}</h3><p class="ln">${escaped(option.summary)}</p></article>`,
269
+ )
270
+ .join(
271
+ '',
272
+ )}</div><blockquote class="pull">${iconSvg({ name: 'quote', size: 36 })}<p class="lab">${escaped(chrome.decision)}</p><p class="big">${escaped(decisionRecord.decision)}</p></blockquote><p class="lab">${escaped(chrome.consequences)}</p><ul class="cons">${decisionRecord.consequences.map((consequence) => `<li>${iconSvg({ name: 'check', size: 18 })}<span>${escaped(consequence)}</span></li>`).join('')}</ul></div>`,
273
+ });
274
+ };
275
+
276
+ export const decisionsSection = (opts: { ctx: ISectionContext }): string => {
277
+ const { decisions } = opts.ctx.spec;
278
+ const { chrome } = opts.ctx;
279
+
280
+ if (decisions === undefined) {
281
+ return '';
282
+ }
283
+
284
+ return section({
285
+ id: 'decisions',
286
+ title: chrome.decisions,
287
+ body: `<ol class="dec">${decisions
288
+ .map(
289
+ (item) =>
290
+ `<li><p class="q">${escaped(item.question)}</p><div class="rec"><span class="lab">${escaped(chrome.recommended)}</span><p>${escaped(item.recommended)}</p></div><p class="chg"><span class="lab">${escaped(chrome.changesClaim)}</span>${escaped(item.changes)}</p></li>`,
291
+ )
292
+ .join('')}</ol>`,
293
+ });
294
+ };
295
+
296
+ const table = (opts: { head: string[]; rows: string[][] }): string =>
297
+ `<div class="tw"><table class="stack"><thead><tr>${opts.head.map((cell) => `<th>${escaped(cell)}</th>`).join('')}</tr></thead><tbody>${opts.rows.map((row) => `<tr>${row.join('')}</tr>`).join('')}</tbody></table></div>`;
298
+
299
+ const cell = (opts: { value: string; label?: string; tag?: boolean }): string =>
300
+ `<td${opts.tag === true ? ' class="tag"' : ''}${opts.label === undefined ? '' : ` data-label="${escaped(opts.label)}"`}>${escaped(opts.value)}</td>`;
301
+
302
+ export const evidenceSection = (opts: { ctx: ISectionContext }): string => {
303
+ const { evidence } = opts.ctx.spec;
304
+ const { chrome } = opts.ctx;
305
+
306
+ if (evidence === undefined) {
307
+ return '';
308
+ }
309
+
310
+ return section({
311
+ id: 'evidence',
312
+ title: chrome.evidence,
313
+ body: `<ul class="evs">${evidence
314
+ .map((row) => {
315
+ const word =
316
+ chrome.evidenceLabels[row.label as keyof TChrome['evidenceLabels']] ?? row.label;
317
+
318
+ return `<li class="ev"><span class="badge ev-${escaped(row.label)}">${iconSvg({ name: row.label, size: 15 })}${escaped(word)}</span><b>${escaped(row.claim)}</b><span class="pr">${escaped(row.probe)}</span><span class="rs">${escaped(row.result)}</span></li>`;
319
+ })
320
+ .join('')}</ul>`,
321
+ });
322
+ };
323
+
324
+ export const risksSection = (opts: { ctx: ISectionContext }): string => {
325
+ const { risks } = opts.ctx.spec;
326
+ const { chrome } = opts.ctx;
327
+
328
+ if (risks === undefined) {
329
+ return '';
330
+ }
331
+
332
+ return section({
333
+ id: 'risks',
334
+ title: chrome.risks,
335
+ body: table({
336
+ head: [chrome.risk, chrome.impact, chrome.fallback],
337
+ rows: risks.map((row) => [
338
+ cell({ value: row.risk, label: chrome.risk }),
339
+ cell({ value: row.impact, label: chrome.impact }),
340
+ cell({ value: row.fallback, label: chrome.fallback }),
341
+ ]),
342
+ }),
343
+ });
344
+ };
345
+
346
+ export const logSection = (opts: { ctx: ISectionContext }): string => {
347
+ const { log } = opts.ctx.spec;
348
+
349
+ return log === undefined
350
+ ? ''
351
+ : section({
352
+ id: 'log',
353
+ title: opts.ctx.chrome.log,
354
+ body: `<ul class="log">${log.map((row) => `<li><time>${escaped(row.date)}</time><span>${escaped(row.text)}</span></li>`).join('')}</ul>`,
355
+ });
356
+ };
357
+
358
+ export const linksSection = (opts: { ctx: ISectionContext }): string => {
359
+ const { links } = opts.ctx.spec;
360
+
361
+ return links === undefined
362
+ ? ''
363
+ : section({
364
+ id: 'links',
365
+ title: opts.ctx.chrome.links,
366
+ body: `<ul class="links">${links.map((link) => `<li><a href="${escaped(link.href)}" rel="noopener noreferrer">${escaped(link.label)}</a></li>`).join('')}</ul>`,
367
+ });
368
+ };
369
+
370
+ export { formatNumber };