@venizia/vulcan 0.4.8 → 0.4.9-0
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/base/hooks/antigravity-guards.ts +2 -1
- package/base/hooks/codex-guards.ts +2 -1
- package/base/hooks/guard-manifest.ts +2 -1
- package/base/hooks/guard-package.ts +2 -1
- package/base/hooks/guard-remote-hosts.ts +9 -3
- package/base/hooks/guard-scripting.ts +2 -1
- package/base/hooks/guard-writes.ts +14 -4
- package/base/hooks/post-tool.ts +2 -1
- package/base/hooks/prompt-submit.ts +2 -1
- package/base/hooks/session-start.ts +3 -1
- package/base/hooks/stop.ts +2 -1
- package/base/make/vulcan.mk +1 -4
- package/base/skills/build-a-feature/SKILL.md +1 -1
- package/base/skills/docs-update/SKILL.md +11 -5
- package/base/skills/docs-update/evals/evals.json +1 -1
- package/base/skills/docs-writing/SKILL.md +1 -1
- package/base/skills/plan-a-change/references/spec-card.md +1 -1
- package/base/skills/ship/SKILL.md +1 -1
- package/base/skills/visualize-work/SKILL.md +20 -6
- package/base/skills/visualize-work/references/spec.md +16 -5
- package/package.json +5 -6
- package/src/agents/codex-hooks.ts +11 -10
- package/src/agents/common/types.ts +1 -1
- package/src/agents/exclude.ts +1 -1
- package/src/agents/hooks-json.ts +4 -8
- package/src/agents/prompt.ts +2 -2
- package/src/agents/render.ts +8 -12
- package/src/cli.ts +3 -1
- package/src/commands/doctor.command.ts +3 -1
- package/src/commands/help.command.ts +11 -9
- package/src/commands/init.command.ts +3 -1
- package/src/commands/profile.command.ts +1 -1
- package/src/commands/upgrade.command.ts +5 -3
- package/src/commands/visualize.command.ts +23 -2
- package/src/common/index.ts +2 -0
- package/src/common/layout-folder.ts +2 -20
- package/src/common/record.ts +7 -0
- package/src/common/text.ts +7 -0
- package/src/config/common/constants.ts +13 -1
- package/src/config/common/types.ts +8 -1
- package/src/config/loader.ts +4 -2
- package/src/config/packages.ts +4 -1
- package/src/config/schema.ts +51 -4
- package/src/create/add-app.ts +170 -69
- package/src/create/add-lib.ts +41 -31
- package/src/create/common/constants.ts +1 -0
- package/src/create/common/failure.ts +10 -0
- package/src/create/common/index.ts +2 -0
- package/src/create/common/preset-path.ts +11 -0
- package/src/create/common/types.ts +7 -2
- package/src/create/init-monorepo.ts +5 -2
- package/src/create/lib-preset.ts +22 -17
- package/src/create/names.ts +1 -1
- package/src/create/next.ts +1 -1
- package/src/create/preset-diff.ts +232 -55
- package/src/create/preset-menu.ts +3 -3
- package/src/create/preset.ts +18 -10
- package/src/create/process.ts +4 -2
- package/src/create/scratch.ts +3 -1
- package/src/create/workspace.ts +37 -20
- package/src/doctor/checks.ts +74 -16
- package/src/doctor/runner.ts +2 -0
- package/src/doctor/tags.ts +2 -4
- package/src/hooks/codex-patch.ts +2 -2
- package/src/hooks/common/constants.ts +0 -3
- package/src/hooks/common/types.ts +15 -1
- package/src/hooks/decision.ts +1 -5
- package/src/hooks/guard-git.ts +1 -1
- package/src/hooks/guard-outside.ts +28 -9
- package/src/hooks/guard-package.ts +13 -7
- package/src/hooks/guard-scripting.ts +1 -1
- package/src/hooks/guard-writes.ts +73 -20
- package/src/hooks/owner-reply.ts +1 -1
- package/src/hooks/project-guards.ts +39 -4
- package/src/hooks/remote-hosts.ts +5 -20
- package/src/hooks/session-digest.ts +7 -0
- package/src/hooks/shell.ts +13 -4
- package/src/hooks/trusted-scripts.ts +80 -4
- package/src/init/common/types.ts +1 -1
- package/src/init/scaffold.ts +2 -2
- package/src/local/clean.ts +1 -1
- package/src/local/scan.ts +2 -2
- package/src/manifest/render.ts +20 -11
- package/src/owner/profile.ts +1 -3
- package/src/owner/shape.ts +1 -1
- package/src/owner/survey.ts +27 -18
- package/src/router.ts +4 -1
- package/src/rules/common/types.ts +1 -1
- package/src/signals/state.ts +1 -4
- package/src/sync/agent-removal.ts +7 -10
- package/src/sync/claude-launch.ts +36 -1
- package/src/sync/common/constants.ts +4 -0
- package/src/sync/common/index.ts +1 -0
- package/src/sync/common/symlink.ts +9 -0
- package/src/sync/common/types.ts +2 -2
- package/src/sync/planner.ts +10 -12
- package/src/sync/settings.ts +1 -1
- package/src/ui/keyboard.ts +3 -1
- package/src/ui/prompt.ts +4 -2
- package/src/visualize/assets.ts +370 -195
- package/src/visualize/charts.ts +11 -2
- package/src/visualize/compare-css.ts +30 -0
- package/src/visualize/compare-render.ts +194 -0
- package/src/visualize/compare-schema.ts +81 -0
- package/src/visualize/compare-validate.ts +126 -0
- package/src/visualize/constants.ts +29 -3
- package/src/visualize/diagrams.ts +1 -1
- package/src/visualize/gate.ts +136 -0
- package/src/visualize/icons.ts +5 -2
- package/src/visualize/index.ts +2 -0
- package/src/visualize/kinds-css.ts +54 -0
- package/src/visualize/kinds-render.ts +693 -0
- package/src/visualize/kinds-schema.ts +148 -0
- package/src/visualize/kinds-validate.ts +184 -0
- package/src/visualize/labels-vi.ts +109 -0
- package/src/visualize/labels.ts +49 -0
- package/src/visualize/layout.ts +10 -5
- package/src/visualize/page.ts +99 -61
- package/src/visualize/render.ts +48 -7
- package/src/visualize/schema.ts +21 -1
- package/src/visualize/sections.ts +115 -34
- package/src/visualize/sources.ts +270 -0
- package/src/visualize/theme.ts +472 -0
- package/src/visualize/validate.ts +6 -0
- package/src/wiki/anchors.ts +1 -1
- package/src/wiki/source-links.ts +3 -5
|
@@ -6,6 +6,7 @@ import type { IDrawing } from './diagrams.ts';
|
|
|
6
6
|
import { iconSvg } from './icons.ts';
|
|
7
7
|
import { columnsOf, escapeText, figureWidth, renderFigure, renderPathList } from './layout.ts';
|
|
8
8
|
import type { TVisualizeSpec } from './schema.ts';
|
|
9
|
+
import { SourceRefs } from './sources.ts';
|
|
9
10
|
|
|
10
11
|
/** 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
12
|
export interface ISectionContext {
|
|
@@ -32,25 +33,60 @@ export const chip = (opts: {
|
|
|
32
33
|
}): string =>
|
|
33
34
|
`<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
|
|
|
36
|
+
/** A part of the page: its title, then its body, each part a slide of its own. */
|
|
35
37
|
export const section = (opts: {
|
|
36
38
|
id: string;
|
|
37
39
|
title: string;
|
|
38
40
|
body: string;
|
|
39
41
|
extra?: string;
|
|
40
42
|
}): string =>
|
|
41
|
-
`<section class="
|
|
43
|
+
`<section class="part${opts.extra === undefined ? '' : ` ${opts.extra}`}" id="${opts.id}" data-slide><div class="wrap"><h2 class="sh">${escaped(opts.title)}</h2>${opts.body}</div></section>`;
|
|
42
44
|
|
|
43
|
-
/**
|
|
45
|
+
/** The in-page links of the top bar: the parts that exist, in the order of the page. */
|
|
46
|
+
export const sectionLinks = (opts: {
|
|
47
|
+
spec: TVisualizeSpec;
|
|
48
|
+
chrome: TChrome;
|
|
49
|
+
}): { id: string; title: string }[] => {
|
|
50
|
+
const { spec, chrome } = opts;
|
|
51
|
+
const parts: [boolean, string, string][] = [
|
|
52
|
+
[spec.flow !== undefined, 'flow', chrome.flow],
|
|
53
|
+
[spec.minimap !== undefined, 'minimap', chrome.minimap],
|
|
54
|
+
[spec.strip !== undefined, 'next', chrome.next],
|
|
55
|
+
[spec.architecture !== undefined, 'architecture', chrome.architecture],
|
|
56
|
+
[spec.compare !== undefined, 'compare', chrome.compareView],
|
|
57
|
+
[spec.sequence !== undefined, 'sequence', chrome.sequence],
|
|
58
|
+
[spec.lifecycle !== undefined, 'lifecycle', chrome.lifecycle],
|
|
59
|
+
[spec.tree !== undefined, 'tree', chrome.tree],
|
|
60
|
+
[spec.comparison !== undefined, 'comparison', chrome.comparison],
|
|
61
|
+
[spec.ideaMap !== undefined, 'idea-map', chrome.ideaMap],
|
|
62
|
+
[spec.explainer !== undefined, 'explainer', chrome.explainer],
|
|
63
|
+
[spec.timeline !== undefined, 'timeline', chrome.timeline],
|
|
64
|
+
[spec.findings !== undefined, 'findings', chrome.findings],
|
|
65
|
+
[spec.beforeAfter !== undefined, 'before-after', `${chrome.before} / ${chrome.after}`],
|
|
66
|
+
[spec.decisionRecord !== undefined, 'decision-record', chrome.decisionRecord],
|
|
67
|
+
[spec.decisions !== undefined, 'decisions', chrome.decisions],
|
|
68
|
+
[spec.evidence !== undefined, 'evidence', chrome.evidence],
|
|
69
|
+
[spec.risks !== undefined, 'risks', chrome.risks],
|
|
70
|
+
[spec.log !== undefined, 'log', chrome.log],
|
|
71
|
+
[spec.terms !== undefined, 'terms', chrome.terms],
|
|
72
|
+
[SourceRefs.entries({ spec, chrome }).length > 0, 'sources', chrome.sources],
|
|
73
|
+
[spec.links !== undefined, 'links', chrome.links],
|
|
74
|
+
];
|
|
75
|
+
|
|
76
|
+
return parts.filter(([exists]) => exists).map(([, id, title]) => ({ id, title }));
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
/** A drawing in a dark window; below the width where its text would pass 12 px the list takes its place. */
|
|
44
80
|
export const figure = (opts: { ctx: ISectionContext; drawing: IDrawing }): string => {
|
|
45
81
|
const width = Math.round(opts.drawing.width);
|
|
46
82
|
|
|
47
83
|
opts.ctx.fits.add(width);
|
|
48
84
|
|
|
49
|
-
return `<div class="fig f${width}">${opts.drawing.svg}</div>${opts.drawing.fallback}
|
|
85
|
+
return `<div class="win"><div class="fig f${width}">${opts.drawing.svg}</div>${opts.drawing.fallback}</div>`;
|
|
50
86
|
};
|
|
51
87
|
|
|
52
88
|
/** JSON for a `<script type="application/json">`: nothing in it can close the tag or start a comment. */
|
|
53
|
-
|
|
89
|
+
const jsonForScript = (opts: { value: unknown }): string =>
|
|
54
90
|
JSON.stringify(opts.value)
|
|
55
91
|
.replaceAll('<', '\\u003c')
|
|
56
92
|
.replaceAll('>', '\\u003e')
|
|
@@ -58,6 +94,14 @@ export const jsonForScript = (opts: { value: unknown }): string =>
|
|
|
58
94
|
.replaceAll('
', '\\u2028')
|
|
59
95
|
.replaceAll('
', '\\u2029');
|
|
60
96
|
|
|
97
|
+
/** One variant of an arrow as a short line, drawn with the same rules as the arrows of the figure. */
|
|
98
|
+
const variantSwatch = (opts: { variant: string }): string =>
|
|
99
|
+
`<svg class="lg" viewBox="0 0 44 12" aria-hidden="true"><g class="edge ${escaped(opts.variant)}"><path d="M0 6H44"/></g></svg>`;
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* The flow lives in the hero: the figure on the slab, its phone list, the legend, then the steps to press and the
|
|
103
|
+
* line that says what is picked. Without script the steps are a plain list with their text.
|
|
104
|
+
*/
|
|
61
105
|
export const flowSection = (opts: { ctx: ISectionContext }): string => {
|
|
62
106
|
const { flow } = opts.ctx.spec;
|
|
63
107
|
const { chrome } = opts.ctx;
|
|
@@ -73,29 +117,65 @@ export const flowSection = (opts: { ctx: ISectionContext }): string => {
|
|
|
73
117
|
...new Set(flow.nodes.flatMap((node) => (node.state === undefined ? [] : [node.state]))),
|
|
74
118
|
];
|
|
75
119
|
const steps = flow.steps;
|
|
76
|
-
const
|
|
120
|
+
const legend = [
|
|
121
|
+
...states.map((state) => `<li>${chip({ chrome, state })}</li>`),
|
|
122
|
+
...(kinds.length > 1 ? kinds.map((kind) => `<li>${escaped(kind)}</li>`) : []),
|
|
123
|
+
...(variants.length > 1
|
|
124
|
+
? variants.map(
|
|
125
|
+
(variant) => `<li>${variantSwatch({ variant })}<span>${escaped(variant)}</span></li>`,
|
|
126
|
+
)
|
|
127
|
+
: []),
|
|
128
|
+
];
|
|
129
|
+
const play =
|
|
77
130
|
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
|
-
: ''
|
|
131
|
+
? `<button class="btn" id="play" type="button" aria-pressed="false" data-play="${escaped(chrome.play)}" data-pause="${escaped(chrome.pause)}">${escaped(chrome.play)}</button>`
|
|
132
|
+
: '';
|
|
133
|
+
const all =
|
|
80
134
|
steps.length > 0
|
|
81
|
-
? `<button
|
|
82
|
-
: ''
|
|
83
|
-
].join('');
|
|
135
|
+
? `<button class="btn" id="all" type="button" hidden>${escaped(chrome.allSteps)}</button>`
|
|
136
|
+
: '';
|
|
84
137
|
|
|
85
138
|
opts.ctx.fits.add(width);
|
|
86
139
|
|
|
87
|
-
//
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
140
|
+
// A box that has a source says it in its detail line: on hover, and in the phone list.
|
|
141
|
+
const shown = {
|
|
142
|
+
...flow,
|
|
143
|
+
nodes: flow.nodes.map((node) =>
|
|
144
|
+
node.source === undefined
|
|
145
|
+
? node
|
|
146
|
+
: {
|
|
147
|
+
...node,
|
|
148
|
+
detail: SourceRefs.withSource({
|
|
149
|
+
text: node.detail ?? node.sublabel,
|
|
150
|
+
source: node.source,
|
|
151
|
+
}),
|
|
152
|
+
},
|
|
153
|
+
),
|
|
154
|
+
};
|
|
155
|
+
// The script reads the step's note whole: its source goes after it there, and in the markup it is its own element.
|
|
156
|
+
const stepsJson = steps.map((step) =>
|
|
157
|
+
step.source === undefined
|
|
158
|
+
? step
|
|
159
|
+
: {
|
|
160
|
+
title: step.title,
|
|
161
|
+
note: SourceRefs.withSource({ text: step.note, source: step.source }),
|
|
162
|
+
nodes: step.nodes,
|
|
163
|
+
edges: step.edges,
|
|
164
|
+
},
|
|
165
|
+
);
|
|
166
|
+
|
|
167
|
+
// The figure, its phone list, the legend, then the steps: a sibling order the page CSS relies on to swap the figure for the list.
|
|
168
|
+
return `<figure class="figure" id="flow"><p class="lab">${escaped(chrome.flow)}</p><div class="fig f${width}">${renderFigure({ flow: shown })}</div>${renderPathList({ flow: shown })}${
|
|
169
|
+
legend.length === 0 ? '' : `<ul class="legend">${legend.join('')}</ul>`
|
|
170
|
+
}${
|
|
171
|
+
steps.length > 0
|
|
172
|
+
? `<ol class="steps">${steps.map((step, index) => `<li><button type="button" aria-pressed="false"><b>${escaped(step.title)}</b><span>${index + 1} / ${steps.length}</span></button><p class="explain">${escaped(step.note)}${step.source === undefined ? '' : ` ${SourceRefs.html({ source: step.source })}`}</p></li>`).join('')}</ol>`
|
|
173
|
+
: ''
|
|
174
|
+
}<div class="say js-only"><p id="say" aria-live="polite">${escaped(chrome.detailHint)}</p><div class="ctl">${play}${all}</div></div>${
|
|
175
|
+
steps.length > 0
|
|
176
|
+
? `<script type="application/json" id="steps">${jsonForScript({ value: stepsJson })}</script>`
|
|
177
|
+
: ''
|
|
178
|
+
}</figure>`;
|
|
99
179
|
};
|
|
100
180
|
|
|
101
181
|
export const architectureSection = (opts: { ctx: ISectionContext }): string => {
|
|
@@ -135,14 +215,14 @@ export const comparisonSection = (opts: { ctx: ISectionContext }): string => {
|
|
|
135
215
|
const cards = comparison.options
|
|
136
216
|
.map(
|
|
137
217
|
(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>`}<
|
|
218
|
+
`<article class="opt${option.recommended === true ? ' rec' : ''}">${option.recommended === true ? `<span class="tag">${escaped(chrome.recommended)}</span>` : ''}<p class="tot">${totals[index]}<small> ${escaped(chrome.outOf)} ${max}</small></p><h3>${escaped(option.name)}</h3>${option.line === undefined ? '' : `<p class="ln">${escaped(option.line)}</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
219
|
)
|
|
140
220
|
.join('');
|
|
141
221
|
|
|
142
222
|
return section({
|
|
143
223
|
id: 'comparison',
|
|
144
224
|
title: chrome.comparison,
|
|
145
|
-
body: `<div class="
|
|
225
|
+
body: `<div class="ranks"><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
226
|
});
|
|
147
227
|
};
|
|
148
228
|
|
|
@@ -168,7 +248,7 @@ export const explainerSection = (opts: { ctx: ISectionContext }): string => {
|
|
|
168
248
|
return section({
|
|
169
249
|
id: 'explainer',
|
|
170
250
|
title: opts.ctx.chrome.explainer,
|
|
171
|
-
body: `<ol class="
|
|
251
|
+
body: `<ol class="ex">${explainer.steps
|
|
172
252
|
.map(
|
|
173
253
|
(step, index) =>
|
|
174
254
|
`<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>`,
|
|
@@ -197,6 +277,7 @@ export const timelineSection = (opts: { ctx: ISectionContext }): string => {
|
|
|
197
277
|
});
|
|
198
278
|
};
|
|
199
279
|
|
|
280
|
+
/** Big numbers as fields: a tint and an icon for a state, plain for a number that is only a number. */
|
|
200
281
|
export const tilesHtml = (opts: {
|
|
201
282
|
tiles: { value: string; label: string; state?: string }[];
|
|
202
283
|
chrome: TChrome;
|
|
@@ -236,10 +317,10 @@ export const beforeAfterSection = (opts: { ctx: ISectionContext }): string => {
|
|
|
236
317
|
items: { text: string; change?: string }[];
|
|
237
318
|
kind: TChangeKind;
|
|
238
319
|
}): string =>
|
|
239
|
-
`<section><h3>${escaped(given.title)}</h3><ul>${given.items
|
|
320
|
+
`<section class="ba"><h3>${escaped(given.title)}</h3><ul>${given.items
|
|
240
321
|
.map((item) =>
|
|
241
322
|
item.change === given.kind
|
|
242
|
-
? `<li class="${given.kind === ChangeKinds.ADDED ? 'add' : 'del'}">${iconSvg({ name: given.kind === ChangeKinds.ADDED ? 'plus' : 'minus', size: 16 })}<span><
|
|
323
|
+
? `<li class="${given.kind === ChangeKinds.ADDED ? 'add' : 'del'}">${iconSvg({ name: given.kind === ChangeKinds.ADDED ? 'plus' : 'minus', size: 16 })}<span><b class="wd">${escaped(given.kind === ChangeKinds.ADDED ? chrome.added : chrome.removed)}</b><span class="tx">${escaped(item.text)}</span></span></li>`
|
|
243
324
|
: `<li class="same">${iconSvg({ name: 'minus', size: 16 })}<span>${escaped(item.text)}</span></li>`,
|
|
244
325
|
)
|
|
245
326
|
.join('')}</ul></section>`;
|
|
@@ -262,14 +343,14 @@ export const decisionRecordSection = (opts: { ctx: ISectionContext }): string =>
|
|
|
262
343
|
return section({
|
|
263
344
|
id: 'decision-record',
|
|
264
345
|
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
|
|
346
|
+
body: `<div class="dr"><div><p class="lab">${escaped(chrome.context)}</p><p class="ctx">${escaped(decisionRecord.context)}</p></div><div><p class="lab">${escaped(chrome.optionsConsidered)}</p><div class="opts n${decisionRecord.options.length}">${decisionRecord.options
|
|
266
347
|
.map(
|
|
267
348
|
(option) =>
|
|
268
349
|
`<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
350
|
)
|
|
270
351
|
.join(
|
|
271
352
|
'',
|
|
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>`,
|
|
353
|
+
)}</div></div><blockquote class="pull">${iconSvg({ name: 'quote', size: 36 })}<p class="lab">${escaped(chrome.decision)}</p><p class="big">${escaped(decisionRecord.decision)}</p></blockquote><div><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></div>`,
|
|
273
354
|
});
|
|
274
355
|
};
|
|
275
356
|
|
|
@@ -284,10 +365,10 @@ export const decisionsSection = (opts: { ctx: ISectionContext }): string => {
|
|
|
284
365
|
return section({
|
|
285
366
|
id: 'decisions',
|
|
286
367
|
title: chrome.decisions,
|
|
287
|
-
body: `<ol class="
|
|
368
|
+
body: `<ol class="qs">${decisions
|
|
288
369
|
.map(
|
|
289
370
|
(item) =>
|
|
290
|
-
`<li
|
|
371
|
+
`<li class="q"><div><h3>${escaped(item.question)}</h3><p class="chg"><span class="lab">${escaped(chrome.changesClaim)}</span>${escaped(item.changes)}</p></div><div class="rec"><b>${escaped(chrome.recommended)}</b><strong>${escaped(item.recommended)}</strong></div></li>`,
|
|
291
372
|
)
|
|
292
373
|
.join('')}</ol>`,
|
|
293
374
|
});
|
|
@@ -310,12 +391,12 @@ export const evidenceSection = (opts: { ctx: ISectionContext }): string => {
|
|
|
310
391
|
return section({
|
|
311
392
|
id: 'evidence',
|
|
312
393
|
title: chrome.evidence,
|
|
313
|
-
body: `<ul class="
|
|
394
|
+
body: `<ul class="ledger">${evidence
|
|
314
395
|
.map((row) => {
|
|
315
396
|
const word =
|
|
316
397
|
chrome.evidenceLabels[row.label as keyof TChrome['evidenceLabels']] ?? row.label;
|
|
317
398
|
|
|
318
|
-
return `<li class="ev"><span class="badge ev-${escaped(row.label)}">${iconSvg({ name: row.label, size:
|
|
399
|
+
return `<li class="ev"><span class="badge ev-${escaped(row.label)}">${iconSvg({ name: row.label, size: 16 })}${escaped(word)}</span><span class="cl"><b>${escaped(row.claim)}</b><span class="pr">${escaped(row.probe)}</span></span><span class="rs">${escaped(row.result)}</span></li>`;
|
|
319
400
|
})
|
|
320
401
|
.join('')}</ul>`,
|
|
321
402
|
});
|
|
@@ -363,7 +444,7 @@ export const linksSection = (opts: { ctx: ISectionContext }): string => {
|
|
|
363
444
|
: section({
|
|
364
445
|
id: 'links',
|
|
365
446
|
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>`,
|
|
447
|
+
body: `<ul class="links">${links.map((link) => `<li><a href="${escaped(link.href)}" rel="noopener noreferrer"><span>${escaped(link.label)}</span>${iconSvg({ name: 'arrow', size: 18 })}</a></li>`).join('')}</ul>`,
|
|
367
448
|
});
|
|
368
449
|
};
|
|
369
450
|
|
|
@@ -0,0 +1,270 @@
|
|
|
1
|
+
import { z } from 'zod';
|
|
2
|
+
import type { TChrome } from './constants.ts';
|
|
3
|
+
import { escapeText } from './layout.ts';
|
|
4
|
+
import type { TVisualizeSpec } from './schema.ts';
|
|
5
|
+
|
|
6
|
+
/** One line of plain text: no markup is interpreted anywhere, it is all escaped. */
|
|
7
|
+
const text = (max: number) =>
|
|
8
|
+
z
|
|
9
|
+
.string()
|
|
10
|
+
.max(max)
|
|
11
|
+
.regex(/^(?=.*\S)[^\p{Cc}--]+$/u, 'one line of text, not blank');
|
|
12
|
+
|
|
13
|
+
/** The limits of the sources and the terms. */
|
|
14
|
+
export class SourceLimits {
|
|
15
|
+
static readonly COMMIT_LENGTH = 40;
|
|
16
|
+
static readonly MAX_TERMS = 12;
|
|
17
|
+
static readonly MAX_TERM = 40;
|
|
18
|
+
static readonly MAX_MEANING = 200;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Where a claim comes from: a repository, the commit it was read at, a path in it and, when it helps, the lines. The shape
|
|
23
|
+
* is checked by `SourceRefs.check` (a commit is 40 lowercase hex characters, a path is relative), so the refusal says why.
|
|
24
|
+
*/
|
|
25
|
+
export const SOURCE_SCHEMA = z.strictObject({
|
|
26
|
+
repo: text(100).describe('the repository, like owner/name'),
|
|
27
|
+
commit: text(64).describe('the full commit: exactly 40 lowercase hex characters'),
|
|
28
|
+
path: text(200).describe('a path inside the repository: relative, without ..'),
|
|
29
|
+
lines: text(16).optional().describe('12 or 12-30, the start not after the end'),
|
|
30
|
+
});
|
|
31
|
+
|
|
32
|
+
/** The words of the page that a reader may not know, each with what it means here. */
|
|
33
|
+
export const TERMS_SCHEMA = z
|
|
34
|
+
.array(
|
|
35
|
+
z.strictObject({
|
|
36
|
+
term: text(SourceLimits.MAX_TERM),
|
|
37
|
+
meaning: text(SourceLimits.MAX_MEANING),
|
|
38
|
+
}),
|
|
39
|
+
)
|
|
40
|
+
.min(1)
|
|
41
|
+
.max(SourceLimits.MAX_TERMS);
|
|
42
|
+
|
|
43
|
+
export type TSource = z.output<typeof SOURCE_SCHEMA>;
|
|
44
|
+
export type TTerms = z.output<typeof TERMS_SCHEMA>;
|
|
45
|
+
|
|
46
|
+
/** A source and every place on the page that points at it. */
|
|
47
|
+
export interface ISourceEntry {
|
|
48
|
+
text: string;
|
|
49
|
+
by: string[];
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** What holds a source: a box of the flow, a step of the flow, a box of the compare view. */
|
|
53
|
+
type TSourceHolder = 'flow' | 'step' | 'compare';
|
|
54
|
+
|
|
55
|
+
interface ISourceUse {
|
|
56
|
+
place: string;
|
|
57
|
+
holder: TSourceHolder;
|
|
58
|
+
label: string;
|
|
59
|
+
source: TSource;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
const escaped = (value: string): string => escapeText({ value });
|
|
63
|
+
|
|
64
|
+
const REPO = /^[A-Za-z0-9][A-Za-z0-9._-]*(\/[A-Za-z0-9][A-Za-z0-9._-]*)*$/;
|
|
65
|
+
const COMMIT = /^[0-9a-f]{40}$/;
|
|
66
|
+
const LINES = /^([1-9]\d{0,6})(?:-([1-9]\d{0,6}))?$/;
|
|
67
|
+
|
|
68
|
+
/** Sources: how one is written, checked and listed. */
|
|
69
|
+
export class SourceRefs {
|
|
70
|
+
/** `repo@commit:path:lines`, the commit in full. */
|
|
71
|
+
static textOf(opts: { source: TSource }): string {
|
|
72
|
+
const { repo, commit, path, lines } = opts.source;
|
|
73
|
+
|
|
74
|
+
return `${repo}@${commit}:${path}${lines === undefined ? '' : `:${lines}`}`;
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
/** A line of text with the source after it. */
|
|
78
|
+
static withSource(opts: { text: string | undefined; source: TSource }): string {
|
|
79
|
+
const source = SourceRefs.textOf({ source: opts.source });
|
|
80
|
+
|
|
81
|
+
return opts.text === undefined ? source : `${opts.text} ${source}`;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** The source as markup: its text in a code element, escaped like every other text. */
|
|
85
|
+
static html(opts: { source: TSource }): string {
|
|
86
|
+
return `<code class="src">${escaped(SourceRefs.textOf({ source: opts.source }))}</code>`;
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/** What is wrong with one source, in words, or nothing. */
|
|
90
|
+
static problemsOf(opts: { place: string; source: TSource }): string[] {
|
|
91
|
+
const { place, source } = opts;
|
|
92
|
+
const problems: string[] = [];
|
|
93
|
+
|
|
94
|
+
if (!REPO.test(source.repo)) {
|
|
95
|
+
problems.push(
|
|
96
|
+
`${place}: repo '${source.repo}' is not owner/name (letters, digits, . _ - and /)`,
|
|
97
|
+
);
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
if (!COMMIT.test(source.commit)) {
|
|
101
|
+
problems.push(
|
|
102
|
+
`${place}: commit '${source.commit}' is not exactly ${SourceLimits.COMMIT_LENGTH} lowercase hex characters - give the full commit, not a short one or a branch`,
|
|
103
|
+
);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
if (/^([\\/]|[A-Za-z]:)/.test(source.path)) {
|
|
107
|
+
problems.push(
|
|
108
|
+
`${place}: path '${source.path}' is absolute - give it from the repository root`,
|
|
109
|
+
);
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
if (source.path.includes('..')) {
|
|
113
|
+
problems.push(`${place}: path '${source.path}' contains '..'`);
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
// A path is a path in the repository, not an address, a home folder or an escaped path.
|
|
117
|
+
if (/^~|:\/\/|%|[․‥….]/.test(source.path)) {
|
|
118
|
+
problems.push(
|
|
119
|
+
`${place}: path '${source.path}' is not a plain path inside the repository (no address, no ~, no % escapes)`,
|
|
120
|
+
);
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
if (source.lines !== undefined) {
|
|
124
|
+
const found = LINES.exec(source.lines);
|
|
125
|
+
|
|
126
|
+
if (found === null) {
|
|
127
|
+
problems.push(`${place}: lines '${source.lines}' is not 12 or 12-30`);
|
|
128
|
+
} else if (Number(found[1]) > Number(found[2] ?? found[1])) {
|
|
129
|
+
problems.push(`${place}: lines '${source.lines}' starts after it ends`);
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
return problems;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** Every source of the page with the place that holds it, in the order the page shows them. */
|
|
137
|
+
private static uses(opts: { spec: TVisualizeSpec }): ISourceUse[] {
|
|
138
|
+
const { flow, compare } = opts.spec;
|
|
139
|
+
const found: ISourceUse[] = [];
|
|
140
|
+
|
|
141
|
+
for (const [index, node] of (flow?.nodes ?? []).entries()) {
|
|
142
|
+
if (node.source !== undefined) {
|
|
143
|
+
found.push({
|
|
144
|
+
place: `flow.nodes[${index}].source`,
|
|
145
|
+
holder: 'flow',
|
|
146
|
+
label: node.label,
|
|
147
|
+
source: node.source,
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
for (const [index, step] of (flow?.steps ?? []).entries()) {
|
|
153
|
+
if (step.source !== undefined) {
|
|
154
|
+
found.push({
|
|
155
|
+
place: `flow.steps[${index}].source`,
|
|
156
|
+
holder: 'step',
|
|
157
|
+
label: step.title,
|
|
158
|
+
source: step.source,
|
|
159
|
+
});
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
for (const [index, node] of (compare?.nodes ?? []).entries()) {
|
|
164
|
+
if (node.source !== undefined) {
|
|
165
|
+
found.push({
|
|
166
|
+
place: `compare.nodes[${index}].source`,
|
|
167
|
+
holder: 'compare',
|
|
168
|
+
label: node.label,
|
|
169
|
+
source: node.source,
|
|
170
|
+
});
|
|
171
|
+
}
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
return found;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/** What a schema cannot say about the sources and the terms. */
|
|
178
|
+
static check(opts: { spec: TVisualizeSpec }): string[] {
|
|
179
|
+
const problems = SourceRefs.uses(opts).flatMap((use) =>
|
|
180
|
+
SourceRefs.problemsOf({ place: use.place, source: use.source }),
|
|
181
|
+
);
|
|
182
|
+
const seen = new Set<string>();
|
|
183
|
+
|
|
184
|
+
for (const item of opts.spec.terms ?? []) {
|
|
185
|
+
const key = item.term.toLowerCase();
|
|
186
|
+
|
|
187
|
+
if (seen.has(key)) {
|
|
188
|
+
problems.push(`terms: '${item.term}' is listed twice`);
|
|
189
|
+
}
|
|
190
|
+
|
|
191
|
+
seen.add(key);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
return problems;
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/** Each distinct source once, in order of appearance, with what points at it. */
|
|
198
|
+
static entries(opts: { spec: TVisualizeSpec; chrome: TChrome }): ISourceEntry[] {
|
|
199
|
+
const { chrome } = opts;
|
|
200
|
+
const word: Record<TSourceHolder, string> = {
|
|
201
|
+
flow: chrome.flow,
|
|
202
|
+
step: chrome.step,
|
|
203
|
+
compare: chrome.compareView,
|
|
204
|
+
};
|
|
205
|
+
const byText = new Map<string, ISourceEntry>();
|
|
206
|
+
|
|
207
|
+
for (const use of SourceRefs.uses(opts)) {
|
|
208
|
+
const key = SourceRefs.textOf({ source: use.source });
|
|
209
|
+
const entry = byText.get(key) ?? { text: key, by: [] };
|
|
210
|
+
const by = `${word[use.holder]}: ${use.label}`;
|
|
211
|
+
|
|
212
|
+
if (!entry.by.includes(by)) {
|
|
213
|
+
entry.by.push(by);
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
byText.set(key, entry);
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
return [...byText.values()];
|
|
220
|
+
}
|
|
221
|
+
|
|
222
|
+
/** The body of the `sources` part: a list, each source once with what points at it. */
|
|
223
|
+
static listHtml(opts: { entries: ISourceEntry[] }): string {
|
|
224
|
+
return `<ol class="srcs">${opts.entries
|
|
225
|
+
.map(
|
|
226
|
+
(entry) =>
|
|
227
|
+
`<li><code class="src">${escaped(entry.text)}</code><span class="by">${entry.by.map(escaped).join(', ')}</span></li>`,
|
|
228
|
+
)
|
|
229
|
+
.join('')}</ol>`;
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/** The terms of the page: shown as a definition list, and each one must show up in the page's other text. */
|
|
234
|
+
export class PageTerms {
|
|
235
|
+
/** The body of the `terms` part: a definition list. */
|
|
236
|
+
static listHtml(opts: { terms: TTerms }): string {
|
|
237
|
+
return `<dl class="terms">${opts.terms
|
|
238
|
+
.map((item) => `<div><dt>${escaped(item.term)}</dt><dd>${escaped(item.meaning)}</dd></div>`)
|
|
239
|
+
.join('')}</dl>`;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/** The text of a page: what is in the body, without scripts, styles, markup, and without the terms part itself. */
|
|
243
|
+
static textOf(opts: { html: string }): string {
|
|
244
|
+
const body = opts.html.slice(opts.html.indexOf('<body>'));
|
|
245
|
+
|
|
246
|
+
return body
|
|
247
|
+
.replace(/<section class="part" id="terms"[\s\S]*?<\/section>/, ' ')
|
|
248
|
+
.replace(/<(script|style)[\s\S]*?<\/\1>/g, ' ')
|
|
249
|
+
.replace(/<[^>]*>/g, ' ')
|
|
250
|
+
.replaceAll('<', '<')
|
|
251
|
+
.replaceAll('>', '>')
|
|
252
|
+
.replaceAll('"', '"')
|
|
253
|
+
.replaceAll(''', "'")
|
|
254
|
+
.replaceAll('&', '&')
|
|
255
|
+
.toLowerCase();
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/** A warning for each term the rest of the page never uses: a word nobody meets needs no definition. */
|
|
259
|
+
static warnings(opts: { html: string; terms: TTerms | undefined }): string[] {
|
|
260
|
+
if (opts.terms === undefined) {
|
|
261
|
+
return [];
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
const page = PageTerms.textOf({ html: opts.html });
|
|
265
|
+
|
|
266
|
+
return opts.terms
|
|
267
|
+
.filter((item) => !page.includes(item.term.toLowerCase()))
|
|
268
|
+
.map((item) => `terms: '${item.term}' never appears in the page text`);
|
|
269
|
+
}
|
|
270
|
+
}
|