@venizia/vulcan 0.4.4 → 0.4.6

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 (88) hide show
  1. package/LICENSE.md +1 -1
  2. package/README.md +13 -0
  3. package/base/agents.json +22 -1
  4. package/base/checks/wiki-anchors.ts +8 -0
  5. package/base/checks/wiki-source-links.ts +8 -0
  6. package/base/claude/remote-hosts.json +1 -1
  7. package/base/claude/settings.json +12 -12
  8. package/base/extensions/vulcan-guards.ts +301 -0
  9. package/base/hooks/antigravity-guards.ts +68 -0
  10. package/base/hooks/codex-guards.ts +66 -0
  11. package/base/hooks/guard-git.ts +38 -9
  12. package/base/hooks/guard-outside.ts +29 -9
  13. package/base/hooks/guard-writes.ts +29 -1
  14. package/base/hooks/session-start.ts +14 -4
  15. package/base/make/vulcan.mk +12 -1
  16. package/base/references/delegation-brief.md +5 -4
  17. package/base/rules.md +2 -2
  18. package/base/skills/docs-writing/SKILL.md +1 -1
  19. package/base/skills/docs-writing/references/agent-documents.md +1 -1
  20. package/base/skills/knowledge-sync/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/SKILL.md +1 -1
  22. package/base/skills/report-back/SKILL.md +1 -1
  23. package/base/skills/retro/SKILL.md +1 -1
  24. package/base/skills/review-a-change/SKILL.md +1 -1
  25. package/base/skills/ship/SKILL.md +1 -1
  26. package/base/skills/visualize-work/SKILL.md +33 -11
  27. package/base/skills/visualize-work/references/spec.md +77 -12
  28. package/package.json +4 -4
  29. package/src/agents/codex-hooks.ts +133 -0
  30. package/src/agents/common/constants.ts +54 -0
  31. package/src/agents/common/schema.ts +10 -1
  32. package/src/agents/common/types.ts +3 -1
  33. package/src/agents/exclude.ts +4 -0
  34. package/src/agents/hooks-json.ts +111 -0
  35. package/src/agents/index.ts +2 -0
  36. package/src/agents/render.ts +5 -4
  37. package/src/agents/resolve.ts +24 -9
  38. package/src/config/common/constants.ts +12 -0
  39. package/src/config/common/types.ts +2 -1
  40. package/src/config/packages.ts +2 -1
  41. package/src/config/schema.ts +84 -5
  42. package/src/create/add-app.ts +2 -2
  43. package/src/create/add-lib.ts +21 -8
  44. package/src/create/common/constants.ts +12 -0
  45. package/src/create/common/types.ts +2 -1
  46. package/src/create/preset-diff.ts +4 -2
  47. package/src/create/workspace.ts +13 -9
  48. package/src/doctor/checks.ts +71 -1
  49. package/src/doctor/common/constants.ts +2 -0
  50. package/src/doctor/runner.ts +6 -0
  51. package/src/hooks/codex-patch.ts +47 -0
  52. package/src/hooks/command-view.ts +97 -0
  53. package/src/hooks/common/constants.ts +46 -0
  54. package/src/hooks/common/types.ts +9 -1
  55. package/src/hooks/decision.ts +50 -8
  56. package/src/hooks/guard-git.ts +64 -5
  57. package/src/hooks/guard-manifest.ts +22 -8
  58. package/src/hooks/guard-outside.ts +38 -6
  59. package/src/hooks/guard-package.ts +15 -12
  60. package/src/hooks/guard-writes.ts +72 -21
  61. package/src/hooks/index.ts +5 -0
  62. package/src/hooks/project-guards.ts +123 -0
  63. package/src/hooks/project-tmp.ts +36 -0
  64. package/src/hooks/remote-hosts.ts +38 -14
  65. package/src/hooks/session-digest.ts +5 -0
  66. package/src/hooks/shell.ts +665 -35
  67. package/src/hooks/trusted-scripts.ts +134 -0
  68. package/src/manifest/render.ts +38 -0
  69. package/src/sync/agent-files.ts +122 -4
  70. package/src/sync/agent-removal.ts +118 -4
  71. package/src/sync/claude-launch.ts +48 -0
  72. package/src/sync/index.ts +1 -0
  73. package/src/sync/local-choice.ts +2 -0
  74. package/src/visualize/assets.ts +195 -54
  75. package/src/visualize/charts.ts +235 -0
  76. package/src/visualize/constants.ts +122 -1
  77. package/src/visualize/diagrams.ts +224 -0
  78. package/src/visualize/icons.ts +28 -0
  79. package/src/visualize/layout.ts +58 -8
  80. package/src/visualize/page.ts +151 -145
  81. package/src/visualize/schema.ts +252 -2
  82. package/src/visualize/sections.ts +370 -0
  83. package/src/visualize/validate.ts +100 -7
  84. package/src/wiki/anchors.ts +118 -0
  85. package/src/wiki/command.ts +110 -0
  86. package/src/wiki/constants.ts +30 -0
  87. package/src/wiki/index.ts +4 -0
  88. package/src/wiki/source-links.ts +186 -0
@@ -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 };
@@ -39,14 +39,10 @@ const blockersOf = (opts: { from: ICell; to: ICell; cells: Map<string, string> }
39
39
  return crossed.flatMap((cell) => cells.get(`${cell.row},${cell.col}`) ?? []);
40
40
  };
41
41
 
42
- /** What a schema cannot say: ids are unique, every edge and step points at something that exists, a cell holds one box. */
43
- export const checkSpec = (opts: { spec: TVisualizeSpec }): string[] => {
42
+ /** The flow: ids are unique, every edge and step points at something that exists, a cell holds one box. */
43
+ const checkFlow = (opts: { flow: NonNullable<TVisualizeSpec['flow']> }): string[] => {
44
44
  const problems: string[] = [];
45
- const { flow } = opts.spec;
46
-
47
- if (flow === undefined) {
48
- return problems;
49
- }
45
+ const { flow } = opts;
50
46
 
51
47
  const ids = new Set<string>();
52
48
  const cells = new Map<string, string>();
@@ -125,3 +121,100 @@ export const checkSpec = (opts: { spec: TVisualizeSpec }): string[] => {
125
121
 
126
122
  return problems;
127
123
  };
124
+
125
+ /** The other kinds: scores match the criteria, links point at boxes, chart data lines up with its labels. */
126
+ const checkKinds = (opts: { spec: TVisualizeSpec }): string[] => {
127
+ const problems: string[] = [];
128
+ const { comparison, architecture, findings, explainer, decisionRecord } = opts.spec;
129
+
130
+ if (comparison !== undefined) {
131
+ for (const option of comparison.options) {
132
+ if (option.scores.length !== comparison.criteria.length) {
133
+ problems.push(
134
+ `comparison.options: '${option.name}' has ${option.scores.length} scores for ${comparison.criteria.length} criteria`,
135
+ );
136
+ }
137
+ }
138
+
139
+ if (comparison.options.filter((option) => option.recommended === true).length > 1) {
140
+ problems.push('comparison.options: only one option can be recommended');
141
+ }
142
+ }
143
+
144
+ if (architecture !== undefined) {
145
+ const ids = new Set<string>();
146
+
147
+ for (const box of architecture.layers.flatMap((layer) => layer.boxes)) {
148
+ if (ids.has(box.id)) {
149
+ problems.push(`architecture: id '${box.id}' is used twice`);
150
+ }
151
+
152
+ ids.add(box.id);
153
+ }
154
+
155
+ for (const link of architecture.links) {
156
+ for (const end of [link.from, link.to]) {
157
+ if (!ids.has(end)) {
158
+ problems.push(
159
+ `architecture.links: '${link.from}>${link.to}' names '${end}', which is not a box`,
160
+ );
161
+ }
162
+ }
163
+
164
+ if (link.from === link.to) {
165
+ problems.push(`architecture.links: '${link.from}>${link.to}' loops to itself`);
166
+ }
167
+ }
168
+ }
169
+
170
+ for (const [index, chart] of (findings?.charts ?? []).entries()) {
171
+ if (chart.type === 'bar' && chart.labels.length !== chart.values.length) {
172
+ problems.push(
173
+ `findings.charts[${index}]: ${chart.labels.length} labels for ${chart.values.length} values`,
174
+ );
175
+ }
176
+
177
+ if (chart.type === 'line') {
178
+ for (const series of chart.series) {
179
+ if (series.values.length !== chart.labels.length) {
180
+ problems.push(
181
+ `findings.charts[${index}]: series '${series.name}' has ${series.values.length} values for ${chart.labels.length} labels`,
182
+ );
183
+ }
184
+ }
185
+ }
186
+
187
+ if (chart.type === 'donut' && chart.parts.every((part) => part.value === 0)) {
188
+ problems.push(`findings.charts[${index}]: every part of the donut is zero`);
189
+ }
190
+ }
191
+
192
+ for (const [index, step] of (explainer?.steps ?? []).entries()) {
193
+ const { diagram } = step;
194
+
195
+ if (
196
+ diagram?.type === 'row' &&
197
+ diagram.arrows !== undefined &&
198
+ diagram.arrows.length !== diagram.nodes.length - 1
199
+ ) {
200
+ problems.push(
201
+ `explainer.steps[${index}]: a row of ${diagram.nodes.length} boxes takes ${diagram.nodes.length - 1} arrow labels`,
202
+ );
203
+ }
204
+ }
205
+
206
+ if (
207
+ decisionRecord !== undefined &&
208
+ decisionRecord.options.filter((option) => option.chosen === true).length > 1
209
+ ) {
210
+ problems.push('decisionRecord.options: only one option can be chosen');
211
+ }
212
+
213
+ return problems;
214
+ };
215
+
216
+ /** What a schema cannot say, for every kind on the page. */
217
+ export const checkSpec = (opts: { spec: TVisualizeSpec }): string[] => [
218
+ ...(opts.spec.flow === undefined ? [] : checkFlow({ flow: opts.spec.flow })),
219
+ ...checkKinds({ spec: opts.spec }),
220
+ ];
@@ -0,0 +1,118 @@
1
+ import { readdirSync, readFileSync, statSync } from 'node:fs';
2
+ import { join } from 'node:path';
3
+ import { AnchorProblems } from './constants.ts';
4
+ import type { TAnchorProblem } from './constants.ts';
5
+
6
+ /**
7
+ * Every in-page anchor the wiki links to must exist on the page it names. The truth is the BUILT html:
8
+ * VitePress does not slugify the way GitHub does (`Construction - Sentinel` is `construction-sentinel`
9
+ * here), so a reimplemented slugifier reports working links as broken. Reading the emitted `id="..."`
10
+ * removes the guess; the check needs a build.
11
+ */
12
+ export interface IBrokenAnchor {
13
+ file: string;
14
+ line: number;
15
+ target: string;
16
+ reason: TAnchorProblem;
17
+ }
18
+
19
+ const walk = (opts: { directory: string; extension: string }): string[] =>
20
+ readdirSync(opts.directory).flatMap((name) => {
21
+ const full = join(opts.directory, name);
22
+
23
+ if (statSync(full).isDirectory()) {
24
+ return walk({ directory: full, extension: opts.extension });
25
+ }
26
+
27
+ return full.endsWith(opts.extension) ? [full] : [];
28
+ });
29
+
30
+ /** `a/b.html` and `a/index.html` answer to `/a/b` and `/a`. */
31
+ const routeOf = (opts: { file: string; root: string; extension: string }): string => {
32
+ const bare = opts.file.slice(opts.root.length + 1).slice(0, -opts.extension.length);
33
+
34
+ return `/${bare.replace(/\/?index$/, '')}`.replace(/\/$/, '') || '/';
35
+ };
36
+
37
+ const normalizeRoute = (opts: { route: string }): string =>
38
+ opts.route.replace(/\/?index$/, '').replace(/\/$/, '') || '/';
39
+
40
+ /** Resolves a link target - empty (same page), absolute or relative - to a dist route. */
41
+ const resolveRoute = (opts: { file: string; target: string; content: string }): string => {
42
+ const { file, target, content } = opts;
43
+
44
+ if (target === '') {
45
+ return routeOf({ file, root: content, extension: '.md' });
46
+ }
47
+
48
+ const bare = target.replace(/\.md$/, '');
49
+
50
+ if (bare.startsWith('/')) {
51
+ return normalizeRoute({ route: bare });
52
+ }
53
+
54
+ const directory = file
55
+ .slice(content.length + 1)
56
+ .split('/')
57
+ .slice(0, -1)
58
+ .join('/');
59
+
60
+ return normalizeRoute({ route: `/${join(directory, bare)}` });
61
+ };
62
+
63
+ const readAnchors = (opts: { dist: string }): Map<string, Set<string>> => {
64
+ const anchorsByRoute = new Map<string, Set<string>>();
65
+
66
+ for (const file of walk({ directory: opts.dist, extension: '.html' })) {
67
+ const ids = new Set(
68
+ [...readFileSync(file, 'utf8').matchAll(/\sid="([^"]+)"/g)].flatMap((match) =>
69
+ match[1] === undefined ? [] : [match[1]],
70
+ ),
71
+ );
72
+
73
+ anchorsByRoute.set(routeOf({ file, root: opts.dist, extension: '.html' }), ids);
74
+ }
75
+
76
+ return anchorsByRoute;
77
+ };
78
+
79
+ /** Checks every `](page#fragment)` link of the markdown under `content` against the ids built in `dist`. */
80
+ export const checkAnchors = (opts: {
81
+ content: string;
82
+ dist: string;
83
+ }): { checked: number; broken: IBrokenAnchor[] } => {
84
+ const { content } = opts;
85
+ const anchorsByRoute = readAnchors({ dist: opts.dist });
86
+ const broken: IBrokenAnchor[] = [];
87
+ let checked = 0;
88
+
89
+ for (const file of walk({ directory: content, extension: '.md' })) {
90
+ // Fenced code carries example links that are not ours to resolve.
91
+ const body = readFileSync(file, 'utf8').replace(/```[\s\S]*?```/g, (match) =>
92
+ match.replace(/[^\n]/g, ' '),
93
+ );
94
+
95
+ for (const [index, text] of body.split('\n').entries()) {
96
+ for (const match of text.matchAll(/\]\(([^)\s]*?)#([\w.-]+)\)/g)) {
97
+ const [, page = '', anchor = ''] = match;
98
+
99
+ if (page.startsWith('http')) {
100
+ continue;
101
+ }
102
+
103
+ checked += 1;
104
+
105
+ const ids = anchorsByRoute.get(resolveRoute({ file, target: page, content }));
106
+ const target = `${page}#${anchor}`;
107
+
108
+ if (ids === undefined) {
109
+ broken.push({ file, line: index + 1, target, reason: AnchorProblems.MISSING_PAGE });
110
+ } else if (!ids.has(anchor)) {
111
+ broken.push({ file, line: index + 1, target, reason: AnchorProblems.DEAD_ANCHOR });
112
+ }
113
+ }
114
+ }
115
+ }
116
+
117
+ return { checked, broken };
118
+ };