@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.
Files changed (126) hide show
  1. package/base/hooks/antigravity-guards.ts +2 -1
  2. package/base/hooks/codex-guards.ts +2 -1
  3. package/base/hooks/guard-manifest.ts +2 -1
  4. package/base/hooks/guard-package.ts +2 -1
  5. package/base/hooks/guard-remote-hosts.ts +9 -3
  6. package/base/hooks/guard-scripting.ts +2 -1
  7. package/base/hooks/guard-writes.ts +14 -4
  8. package/base/hooks/post-tool.ts +2 -1
  9. package/base/hooks/prompt-submit.ts +2 -1
  10. package/base/hooks/session-start.ts +3 -1
  11. package/base/hooks/stop.ts +2 -1
  12. package/base/make/vulcan.mk +1 -4
  13. package/base/skills/build-a-feature/SKILL.md +1 -1
  14. package/base/skills/docs-update/SKILL.md +11 -5
  15. package/base/skills/docs-update/evals/evals.json +1 -1
  16. package/base/skills/docs-writing/SKILL.md +1 -1
  17. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  18. package/base/skills/ship/SKILL.md +1 -1
  19. package/base/skills/visualize-work/SKILL.md +20 -6
  20. package/base/skills/visualize-work/references/spec.md +16 -5
  21. package/package.json +5 -6
  22. package/src/agents/codex-hooks.ts +11 -10
  23. package/src/agents/common/types.ts +1 -1
  24. package/src/agents/exclude.ts +1 -1
  25. package/src/agents/hooks-json.ts +4 -8
  26. package/src/agents/prompt.ts +2 -2
  27. package/src/agents/render.ts +8 -12
  28. package/src/cli.ts +3 -1
  29. package/src/commands/doctor.command.ts +3 -1
  30. package/src/commands/help.command.ts +11 -9
  31. package/src/commands/init.command.ts +3 -1
  32. package/src/commands/profile.command.ts +1 -1
  33. package/src/commands/upgrade.command.ts +5 -3
  34. package/src/commands/visualize.command.ts +23 -2
  35. package/src/common/index.ts +2 -0
  36. package/src/common/layout-folder.ts +2 -20
  37. package/src/common/record.ts +7 -0
  38. package/src/common/text.ts +7 -0
  39. package/src/config/common/constants.ts +13 -1
  40. package/src/config/common/types.ts +8 -1
  41. package/src/config/loader.ts +4 -2
  42. package/src/config/packages.ts +4 -1
  43. package/src/config/schema.ts +51 -4
  44. package/src/create/add-app.ts +170 -69
  45. package/src/create/add-lib.ts +41 -31
  46. package/src/create/common/constants.ts +1 -0
  47. package/src/create/common/failure.ts +10 -0
  48. package/src/create/common/index.ts +2 -0
  49. package/src/create/common/preset-path.ts +11 -0
  50. package/src/create/common/types.ts +7 -2
  51. package/src/create/init-monorepo.ts +5 -2
  52. package/src/create/lib-preset.ts +22 -17
  53. package/src/create/names.ts +1 -1
  54. package/src/create/next.ts +1 -1
  55. package/src/create/preset-diff.ts +232 -55
  56. package/src/create/preset-menu.ts +3 -3
  57. package/src/create/preset.ts +18 -10
  58. package/src/create/process.ts +4 -2
  59. package/src/create/scratch.ts +3 -1
  60. package/src/create/workspace.ts +37 -20
  61. package/src/doctor/checks.ts +74 -16
  62. package/src/doctor/runner.ts +2 -0
  63. package/src/doctor/tags.ts +2 -4
  64. package/src/hooks/codex-patch.ts +2 -2
  65. package/src/hooks/common/constants.ts +0 -3
  66. package/src/hooks/common/types.ts +15 -1
  67. package/src/hooks/decision.ts +1 -5
  68. package/src/hooks/guard-git.ts +1 -1
  69. package/src/hooks/guard-outside.ts +28 -9
  70. package/src/hooks/guard-package.ts +13 -7
  71. package/src/hooks/guard-scripting.ts +1 -1
  72. package/src/hooks/guard-writes.ts +73 -20
  73. package/src/hooks/owner-reply.ts +1 -1
  74. package/src/hooks/project-guards.ts +39 -4
  75. package/src/hooks/remote-hosts.ts +5 -20
  76. package/src/hooks/session-digest.ts +7 -0
  77. package/src/hooks/shell.ts +13 -4
  78. package/src/hooks/trusted-scripts.ts +80 -4
  79. package/src/init/common/types.ts +1 -1
  80. package/src/init/scaffold.ts +2 -2
  81. package/src/local/clean.ts +1 -1
  82. package/src/local/scan.ts +2 -2
  83. package/src/manifest/render.ts +20 -11
  84. package/src/owner/profile.ts +1 -3
  85. package/src/owner/shape.ts +1 -1
  86. package/src/owner/survey.ts +27 -18
  87. package/src/router.ts +4 -1
  88. package/src/rules/common/types.ts +1 -1
  89. package/src/signals/state.ts +1 -4
  90. package/src/sync/agent-removal.ts +7 -10
  91. package/src/sync/claude-launch.ts +36 -1
  92. package/src/sync/common/constants.ts +4 -0
  93. package/src/sync/common/index.ts +1 -0
  94. package/src/sync/common/symlink.ts +9 -0
  95. package/src/sync/common/types.ts +2 -2
  96. package/src/sync/planner.ts +10 -12
  97. package/src/sync/settings.ts +1 -1
  98. package/src/ui/keyboard.ts +3 -1
  99. package/src/ui/prompt.ts +4 -2
  100. package/src/visualize/assets.ts +370 -195
  101. package/src/visualize/charts.ts +11 -2
  102. package/src/visualize/compare-css.ts +30 -0
  103. package/src/visualize/compare-render.ts +194 -0
  104. package/src/visualize/compare-schema.ts +81 -0
  105. package/src/visualize/compare-validate.ts +126 -0
  106. package/src/visualize/constants.ts +29 -3
  107. package/src/visualize/diagrams.ts +1 -1
  108. package/src/visualize/gate.ts +136 -0
  109. package/src/visualize/icons.ts +5 -2
  110. package/src/visualize/index.ts +2 -0
  111. package/src/visualize/kinds-css.ts +54 -0
  112. package/src/visualize/kinds-render.ts +693 -0
  113. package/src/visualize/kinds-schema.ts +148 -0
  114. package/src/visualize/kinds-validate.ts +184 -0
  115. package/src/visualize/labels-vi.ts +109 -0
  116. package/src/visualize/labels.ts +49 -0
  117. package/src/visualize/layout.ts +10 -5
  118. package/src/visualize/page.ts +99 -61
  119. package/src/visualize/render.ts +48 -7
  120. package/src/visualize/schema.ts +21 -1
  121. package/src/visualize/sections.ts +115 -34
  122. package/src/visualize/sources.ts +270 -0
  123. package/src/visualize/theme.ts +472 -0
  124. package/src/visualize/validate.ts +6 -0
  125. package/src/wiki/anchors.ts +1 -1
  126. 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="sec${opts.extra === undefined ? '' : ` ${opts.extra}`}" id="${opts.id}" data-slide><h2 class="lab">${escaped(opts.title)}</h2>${opts.body}</section>`;
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
- /** A drawing in its frame; below the width where its text would pass 12 px the list takes its place. */
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
- export const jsonForScript = (opts: { value: unknown }): string =>
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 controls = [
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 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('');
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
- // 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
- });
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>`}<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>`,
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="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>`}`,
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="steps">${explainer.steps
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><span class="vh">${escaped(given.kind === ChangeKinds.ADDED ? chrome.added : chrome.removed)}: </span>${escaped(item.text)}</span></li>`
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="dec">${decisions
368
+ body: `<ol class="qs">${decisions
288
369
  .map(
289
370
  (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>`,
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="evs">${evidence
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: 15 })}${escaped(word)}</span><b>${escaped(row.claim)}</b><span class="pr">${escaped(row.probe)}</span><span class="rs">${escaped(row.result)}</span></li>`;
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('&lt;', '<')
251
+ .replaceAll('&gt;', '>')
252
+ .replaceAll('&quot;', '"')
253
+ .replaceAll('&#39;', "'")
254
+ .replaceAll('&amp;', '&')
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
+ }