@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.
- package/LICENSE.md +1 -1
- package/README.md +13 -0
- package/base/agents.json +22 -1
- package/base/checks/wiki-anchors.ts +8 -0
- package/base/checks/wiki-source-links.ts +8 -0
- package/base/claude/remote-hosts.json +1 -1
- package/base/claude/settings.json +12 -12
- package/base/extensions/vulcan-guards.ts +301 -0
- package/base/hooks/antigravity-guards.ts +68 -0
- package/base/hooks/codex-guards.ts +66 -0
- package/base/hooks/guard-git.ts +38 -9
- package/base/hooks/guard-outside.ts +29 -9
- package/base/hooks/guard-writes.ts +29 -1
- package/base/hooks/session-start.ts +14 -4
- package/base/make/vulcan.mk +12 -1
- package/base/references/delegation-brief.md +5 -4
- package/base/rules.md +2 -2
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/docs-writing/references/agent-documents.md +1 -1
- package/base/skills/knowledge-sync/SKILL.md +1 -1
- package/base/skills/plan-a-change/SKILL.md +1 -1
- package/base/skills/report-back/SKILL.md +1 -1
- package/base/skills/retro/SKILL.md +1 -1
- package/base/skills/review-a-change/SKILL.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +33 -11
- package/base/skills/visualize-work/references/spec.md +77 -12
- package/package.json +4 -4
- package/src/agents/codex-hooks.ts +133 -0
- package/src/agents/common/constants.ts +54 -0
- package/src/agents/common/schema.ts +10 -1
- package/src/agents/common/types.ts +3 -1
- package/src/agents/exclude.ts +4 -0
- package/src/agents/hooks-json.ts +111 -0
- package/src/agents/index.ts +2 -0
- package/src/agents/render.ts +5 -4
- package/src/agents/resolve.ts +24 -9
- package/src/config/common/constants.ts +12 -0
- package/src/config/common/types.ts +2 -1
- package/src/config/packages.ts +2 -1
- package/src/config/schema.ts +84 -5
- package/src/create/add-app.ts +2 -2
- package/src/create/add-lib.ts +21 -8
- package/src/create/common/constants.ts +12 -0
- package/src/create/common/types.ts +2 -1
- package/src/create/preset-diff.ts +4 -2
- package/src/create/workspace.ts +13 -9
- package/src/doctor/checks.ts +71 -1
- package/src/doctor/common/constants.ts +2 -0
- package/src/doctor/runner.ts +6 -0
- package/src/hooks/codex-patch.ts +47 -0
- package/src/hooks/command-view.ts +97 -0
- package/src/hooks/common/constants.ts +46 -0
- package/src/hooks/common/types.ts +9 -1
- package/src/hooks/decision.ts +50 -8
- package/src/hooks/guard-git.ts +64 -5
- package/src/hooks/guard-manifest.ts +22 -8
- package/src/hooks/guard-outside.ts +38 -6
- package/src/hooks/guard-package.ts +15 -12
- package/src/hooks/guard-writes.ts +72 -21
- package/src/hooks/index.ts +5 -0
- package/src/hooks/project-guards.ts +123 -0
- package/src/hooks/project-tmp.ts +36 -0
- package/src/hooks/remote-hosts.ts +38 -14
- package/src/hooks/session-digest.ts +5 -0
- package/src/hooks/shell.ts +665 -35
- package/src/hooks/trusted-scripts.ts +134 -0
- package/src/manifest/render.ts +38 -0
- package/src/sync/agent-files.ts +122 -4
- package/src/sync/agent-removal.ts +118 -4
- package/src/sync/claude-launch.ts +48 -0
- package/src/sync/index.ts +1 -0
- package/src/sync/local-choice.ts +2 -0
- package/src/visualize/assets.ts +195 -54
- package/src/visualize/charts.ts +235 -0
- package/src/visualize/constants.ts +122 -1
- package/src/visualize/diagrams.ts +224 -0
- package/src/visualize/icons.ts +28 -0
- package/src/visualize/layout.ts +58 -8
- package/src/visualize/page.ts +151 -145
- package/src/visualize/schema.ts +252 -2
- package/src/visualize/sections.ts +370 -0
- package/src/visualize/validate.ts +100 -7
- package/src/wiki/anchors.ts +118 -0
- package/src/wiki/command.ts +110 -0
- package/src/wiki/constants.ts +30 -0
- package/src/wiki/index.ts +4 -0
- 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
|
-
/**
|
|
43
|
-
|
|
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
|
|
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
|
+
};
|