@venizia/vulcan 0.4.8 → 0.4.9-1

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 (179) hide show
  1. package/base/extensions/vulcan-guards.ts +48 -41
  2. package/base/hooks/antigravity-guards.ts +4 -3
  3. package/base/hooks/codex-guards.ts +17 -6
  4. package/base/hooks/guard-git.ts +8 -8
  5. package/base/hooks/guard-manifest.ts +5 -5
  6. package/base/hooks/guard-outside.ts +8 -8
  7. package/base/hooks/guard-package.ts +6 -6
  8. package/base/hooks/guard-remote-hosts.ts +14 -9
  9. package/base/hooks/guard-scripting.ts +6 -6
  10. package/base/hooks/guard-writes.ts +20 -11
  11. package/base/hooks/post-tool.ts +4 -3
  12. package/base/hooks/prompt-submit.ts +4 -3
  13. package/base/hooks/session-start.ts +5 -3
  14. package/base/hooks/stop.ts +4 -3
  15. package/base/hooks/subagent-start.ts +2 -2
  16. package/base/make/vulcan.mk +1 -4
  17. package/base/skills/build-a-feature/SKILL.md +1 -1
  18. package/base/skills/docs-update/SKILL.md +11 -5
  19. package/base/skills/docs-update/evals/evals.json +1 -1
  20. package/base/skills/docs-writing/SKILL.md +1 -1
  21. package/base/skills/plan-a-change/references/spec-card.md +1 -1
  22. package/base/skills/ship/SKILL.md +1 -1
  23. package/base/skills/visualize-work/SKILL.md +29 -6
  24. package/base/skills/visualize-work/references/spec.md +16 -5
  25. package/package.json +5 -6
  26. package/src/agents/atlas-block.ts +43 -43
  27. package/src/agents/codex-hooks.ts +55 -52
  28. package/src/agents/common/types.ts +1 -1
  29. package/src/agents/detect.ts +19 -16
  30. package/src/agents/exclude.ts +97 -98
  31. package/src/agents/hooks-json.ts +41 -43
  32. package/src/agents/local.ts +46 -43
  33. package/src/agents/prompt.ts +45 -42
  34. package/src/agents/render.ts +203 -201
  35. package/src/agents/resolve.ts +133 -134
  36. package/src/agents/table.ts +12 -8
  37. package/src/cli.ts +3 -1
  38. package/src/commands/add.command.ts +2 -2
  39. package/src/commands/agents.command.ts +11 -17
  40. package/src/commands/clean.command.ts +6 -6
  41. package/src/commands/doctor.command.ts +6 -4
  42. package/src/commands/help.command.ts +11 -9
  43. package/src/commands/init.command.ts +14 -8
  44. package/src/commands/preset.command.ts +2 -2
  45. package/src/commands/profile.command.ts +43 -50
  46. package/src/commands/sync.command.ts +109 -111
  47. package/src/commands/upgrade.command.ts +85 -78
  48. package/src/commands/visualize.command.ts +20 -5
  49. package/src/commands/x.command.ts +55 -50
  50. package/src/common/format.ts +23 -21
  51. package/src/common/index.ts +2 -0
  52. package/src/common/json.ts +8 -5
  53. package/src/common/layout-folder.ts +96 -111
  54. package/src/common/paths.ts +14 -12
  55. package/src/common/record.ts +7 -0
  56. package/src/common/text.ts +7 -0
  57. package/src/config/common/constants.ts +13 -1
  58. package/src/config/common/types.ts +8 -1
  59. package/src/config/loader.ts +53 -48
  60. package/src/config/packages.ts +17 -11
  61. package/src/config/schema.ts +54 -7
  62. package/src/create/add-app.ts +604 -493
  63. package/src/create/add-lib.ts +249 -242
  64. package/src/create/bunfig.ts +26 -23
  65. package/src/create/checks.ts +36 -34
  66. package/src/create/common/constants.ts +1 -0
  67. package/src/create/common/failure.ts +10 -0
  68. package/src/create/common/index.ts +2 -0
  69. package/src/create/common/preset-path.ts +11 -0
  70. package/src/create/common/types.ts +7 -2
  71. package/src/create/diff.ts +21 -23
  72. package/src/create/dockerignore.ts +26 -24
  73. package/src/create/files.ts +7 -5
  74. package/src/create/init-monorepo.ts +78 -80
  75. package/src/create/lib-preset.ts +62 -61
  76. package/src/create/manifest-json.ts +10 -4
  77. package/src/create/names.ts +217 -210
  78. package/src/create/next.ts +27 -24
  79. package/src/create/plan.ts +15 -12
  80. package/src/create/preset-diff.ts +415 -240
  81. package/src/create/preset-menu.ts +40 -34
  82. package/src/create/preset.ts +207 -194
  83. package/src/create/process.ts +80 -71
  84. package/src/create/scratch.ts +49 -48
  85. package/src/create/workspace.ts +423 -398
  86. package/src/doctor/checks.ts +1069 -998
  87. package/src/doctor/makefile.ts +17 -13
  88. package/src/doctor/runner.ts +88 -116
  89. package/src/doctor/skills.ts +97 -95
  90. package/src/doctor/tags.ts +44 -41
  91. package/src/hooks/codex-patch.ts +27 -24
  92. package/src/hooks/command-view.ts +44 -39
  93. package/src/hooks/common/constants.ts +0 -3
  94. package/src/hooks/common/types.ts +15 -1
  95. package/src/hooks/decision.ts +38 -42
  96. package/src/hooks/guard-git.ts +52 -50
  97. package/src/hooks/guard-manifest.ts +58 -55
  98. package/src/hooks/guard-outside.ts +109 -88
  99. package/src/hooks/guard-package.ts +86 -77
  100. package/src/hooks/guard-scripting.ts +20 -15
  101. package/src/hooks/guard-writes.ts +169 -111
  102. package/src/hooks/owner-reply.ts +128 -128
  103. package/src/hooks/post-tool.ts +94 -93
  104. package/src/hooks/project-guards.ts +93 -55
  105. package/src/hooks/project-tmp.ts +27 -24
  106. package/src/hooks/remote-hosts.ts +157 -149
  107. package/src/hooks/session-digest.ts +99 -95
  108. package/src/hooks/shell.ts +519 -500
  109. package/src/hooks/subagent-card.ts +11 -7
  110. package/src/hooks/trusted-scripts.ts +158 -80
  111. package/src/init/common/types.ts +1 -1
  112. package/src/init/scaffold.ts +137 -134
  113. package/src/local/clean.ts +39 -37
  114. package/src/local/format.ts +21 -17
  115. package/src/local/scan.ts +146 -140
  116. package/src/manifest/render.ts +127 -112
  117. package/src/owner/card.ts +51 -46
  118. package/src/owner/profile.ts +100 -96
  119. package/src/owner/reply-switch.ts +9 -6
  120. package/src/owner/shape.ts +72 -70
  121. package/src/owner/survey.ts +175 -164
  122. package/src/owner/view.ts +62 -59
  123. package/src/owner/violations.ts +119 -123
  124. package/src/router.ts +4 -1
  125. package/src/rules/base.ts +15 -11
  126. package/src/rules/common/types.ts +1 -1
  127. package/src/rules/parser.ts +39 -32
  128. package/src/rules/slots.ts +8 -6
  129. package/src/signals/claims.ts +30 -28
  130. package/src/signals/classify.ts +36 -33
  131. package/src/signals/loop.ts +39 -37
  132. package/src/signals/state.ts +80 -85
  133. package/src/skills/frontmatter.ts +28 -28
  134. package/src/sync/agent-files.ts +217 -199
  135. package/src/sync/agent-removal.ts +62 -68
  136. package/src/sync/atlas-block.ts +45 -43
  137. package/src/sync/base-rules.ts +32 -30
  138. package/src/sync/claude-launch.ts +74 -37
  139. package/src/sync/common/constants.ts +4 -0
  140. package/src/sync/common/index.ts +1 -0
  141. package/src/sync/common/symlink.ts +9 -0
  142. package/src/sync/common/types.ts +2 -2
  143. package/src/sync/exclude.ts +77 -69
  144. package/src/sync/local-choice.ts +50 -47
  145. package/src/sync/planner.ts +64 -68
  146. package/src/sync/prune.ts +52 -48
  147. package/src/sync/settings.ts +167 -168
  148. package/src/ui/capability.ts +12 -7
  149. package/src/ui/keyboard.ts +35 -33
  150. package/src/ui/prompt.ts +81 -77
  151. package/src/visualize/assets.ts +379 -195
  152. package/src/visualize/charts.ts +188 -176
  153. package/src/visualize/compare-css.ts +31 -0
  154. package/src/visualize/compare-render.ts +196 -0
  155. package/src/visualize/compare-schema.ts +81 -0
  156. package/src/visualize/compare-validate.ts +126 -0
  157. package/src/visualize/constants.ts +29 -3
  158. package/src/visualize/diagrams.ts +189 -174
  159. package/src/visualize/gate.ts +136 -0
  160. package/src/visualize/grid-span.ts +34 -0
  161. package/src/visualize/icons.ts +9 -4
  162. package/src/visualize/index.ts +2 -0
  163. package/src/visualize/kinds-css.ts +54 -0
  164. package/src/visualize/kinds-render.ts +698 -0
  165. package/src/visualize/kinds-schema.ts +148 -0
  166. package/src/visualize/kinds-validate.ts +186 -0
  167. package/src/visualize/labels-vi.ts +109 -0
  168. package/src/visualize/labels.ts +53 -0
  169. package/src/visualize/layout.ts +112 -92
  170. package/src/visualize/page.ts +140 -114
  171. package/src/visualize/render.ts +158 -114
  172. package/src/visualize/schema.ts +21 -1
  173. package/src/visualize/sections.ts +401 -309
  174. package/src/visualize/sources.ts +270 -0
  175. package/src/visualize/theme.ts +474 -0
  176. package/src/visualize/validate.ts +15 -5
  177. package/src/wiki/anchors.ts +39 -37
  178. package/src/wiki/command.ts +4 -4
  179. package/src/wiki/source-links.ts +49 -49
@@ -1,21 +1,12 @@
1
- import { iconSvg } from './icons.ts';
1
+ import { IconSet } from './icons.ts';
2
2
  import { NodeStates } from './constants.ts';
3
3
  import type { TChrome } from './constants.ts';
4
- import { escapeText } from './layout.ts';
4
+ import { FigureLayout } from './layout.ts';
5
5
  import type { TVisualizeSpec } from './schema.ts';
6
6
 
7
7
  type TChart = NonNullable<NonNullable<TVisualizeSpec['findings']>['charts']>[number];
8
8
 
9
- const escaped = (value: string): string => escapeText({ value });
10
-
11
- /** 1234567 as 1,234,567 and 0.5 as 0.5: no locale, so the page reads the same everywhere. */
12
- export const formatNumber = (opts: { value: number }): string => {
13
- const rounded = Math.round(opts.value * 100) / 100;
14
- const [whole = '0', fraction] = String(Math.abs(rounded)).split('.');
15
- const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
16
-
17
- return `${rounded < 0 ? '-' : ''}${grouped}${fraction === undefined ? '' : `.${fraction}`}`;
18
- };
9
+ const escaped = (value: string): string => FigureLayout.escapeText({ value });
19
10
 
20
11
  const shorten = (opts: { value: string; max: number }): string =>
21
12
  opts.value.length <= opts.max ? opts.value : `${opts.value.slice(0, opts.max - 1)}…`;
@@ -45,191 +36,212 @@ const niceScale = (opts: {
45
36
 
46
37
  const VIEW_WIDTH = 340;
47
38
 
48
- const barChart = (opts: { chart: Extract<TChart, { type: 'bar' }> }): string => {
49
- const { labels, values } = opts.chart;
50
- const max = Math.max(...values, 1);
51
- const rowHeight = 30;
52
- const left = 120;
53
- const plot = 150;
54
-
55
- return `<svg viewBox="0 0 ${VIEW_WIDTH} ${labels.length * rowHeight + 8}" role="img" aria-label="${escaped(opts.chart.title)}">${labels
56
- .map((label, index) => {
57
- const y = index * rowHeight + 6;
58
- const width = Math.max(2, Math.round(((values[index] ?? 0) / max) * plot));
59
-
60
- return `<g><title>${escaped(label)}: ${formatNumber({ value: values[index] ?? 0 })}${escaped(opts.chart.unit ?? '')}</title><text x="0" y="${y + 16}" class="ct">${escaped(shorten({ value: label, max: 18 }))}</text><rect x="${left}" y="${y + 2}" width="${plot}" height="18" rx="4" class="ctrack"/><path d="${barPath({ x: left, y: y + 2, width, height: 18 })}" fill="var(--s1)"/><text x="${left + width + 6}" y="${y + 16}" class="cv">${formatNumber({ value: values[index] ?? 0 })}${escaped(opts.chart.unit ?? '')}</text></g>`;
61
- })
62
- .join('')}</svg>`;
39
+ const SLOTS = ['var(--s1)', 'var(--s2)', 'var(--s3)', 'var(--s4)', 'var(--s5)'];
40
+
41
+ /** The page colour of a state tone: what waits for the owner is the project's accent, the rest are fixed. */
42
+ const TONE_COLOURS: Record<string, string> = {
43
+ ok: 'var(--ok)',
44
+ warn: 'var(--accent)',
45
+ bad: 'var(--bad)',
46
+ info: 'var(--info)',
47
+ mut: 'var(--muted)',
63
48
  };
64
49
 
65
- const lineChart = (opts: { chart: Extract<TChart, { type: 'line' }> }): string => {
66
- const { labels, series } = opts.chart;
67
- const all = series.flatMap((s) => s.values.slice(0, labels.length));
68
- const scale = niceScale({ min: Math.min(...all), max: Math.max(...all), ticks: 4 });
69
- const left = 44;
70
- const right = 64;
71
- const top = 12;
72
- const height = 150;
73
- const plot = VIEW_WIDTH - left - right;
74
- const x = (index: number): number => left + (index / (labels.length - 1)) * plot;
75
- const y = (value: number): number =>
76
- top + height - ((value - scale.low) / (scale.high - scale.low || 1)) * height;
77
- const ticks: number[] = [];
78
-
79
- for (let value = scale.low; value <= scale.high + scale.step / 2; value += scale.step) {
80
- ticks.push(Math.round(value * 1000) / 1000);
50
+ const donutColour = (opts: { index: number; state?: string }): string =>
51
+ opts.state === undefined
52
+ ? (SLOTS[opts.index] ?? 'var(--s5)')
53
+ : (TONE_COLOURS[NodeStates.toneOf(opts.state)] ?? 'var(--muted)');
54
+
55
+ export class SpecCharts {
56
+ private static barChart(opts: { chart: Extract<TChart, { type: 'bar' }> }): string {
57
+ const { labels, values } = opts.chart;
58
+ const max = Math.max(...values, 1);
59
+ const rowHeight = 30;
60
+ const left = 120;
61
+ const plot = 150;
62
+
63
+ return `<svg viewBox="0 0 ${VIEW_WIDTH} ${labels.length * rowHeight + 8}" role="img" aria-label="${escaped(opts.chart.title)}">${labels
64
+ .map((label, index) => {
65
+ const y = index * rowHeight + 6;
66
+ const width = Math.max(2, Math.round(((values[index] ?? 0) / max) * plot));
67
+
68
+ return `<g><title>${escaped(label)}: ${SpecCharts.formatNumber({ value: values[index] ?? 0 })}${escaped(opts.chart.unit ?? '')}</title><text x="0" y="${y + 16}" class="ct">${escaped(shorten({ value: label, max: 18 }))}</text><rect x="${left}" y="${y + 2}" width="${plot}" height="18" rx="4" class="ctrack"/><path d="${barPath({ x: left, y: y + 2, width, height: 18 })}" fill="var(--s1)"/><text x="${left + width + 6}" y="${y + 16}" class="cv">${SpecCharts.formatNumber({ value: values[index] ?? 0 })}${escaped(opts.chart.unit ?? '')}</text></g>`;
69
+ })
70
+ .join('')}</svg>`;
81
71
  }
82
72
 
83
- const every = labels.length > 6 ? Math.ceil(labels.length / 6) : 1;
84
- // The direct labels sit at the last point of each line; where two would touch, they are pushed apart by 15 px.
85
- const ends = series
86
- .map((s, index) => ({ index, y: y(s.values.slice(0, labels.length).at(-1) ?? 0) }))
87
- .sort((a, b) => a.y - b.y);
88
-
89
- for (let at = 1; at < ends.length; at += 1) {
90
- const previous = ends[at - 1];
91
- const current = ends[at];
92
-
93
- if (previous !== undefined && current !== undefined && current.y - previous.y < 15) {
94
- current.y = previous.y + 15;
73
+ private static lineChart(opts: { chart: Extract<TChart, { type: 'line' }> }): string {
74
+ const { labels, series } = opts.chart;
75
+ const all = series.flatMap((s) => s.values.slice(0, labels.length));
76
+ const scale = niceScale({ min: Math.min(...all), max: Math.max(...all), ticks: 4 });
77
+ const left = 44;
78
+ const right = 64;
79
+ const top = 12;
80
+ const height = 150;
81
+ const plot = VIEW_WIDTH - left - right;
82
+ const x = (index: number): number => left + (index / (labels.length - 1)) * plot;
83
+ const y = (value: number): number =>
84
+ top + height - ((value - scale.low) / (scale.high - scale.low || 1)) * height;
85
+ const ticks: number[] = [];
86
+
87
+ for (let value = scale.low; value <= scale.high + scale.step / 2; value += scale.step) {
88
+ ticks.push(Math.round(value * 1000) / 1000);
95
89
  }
96
- }
97
90
 
98
- const labelY = new Map(ends.map((end) => [end.index, end.y]));
99
-
100
- return `<svg viewBox="0 0 ${VIEW_WIDTH} ${top + height + 34}" role="img" aria-label="${escaped(opts.chart.title)}">${ticks
101
- .map(
102
- (tick) =>
103
- `<line x1="${left}" x2="${VIEW_WIDTH - right}" y1="${y(tick)}" y2="${y(tick)}" class="cgrid"/><text x="${left - 6}" y="${y(tick) + 4}" text-anchor="end" class="ct">${formatNumber({ value: tick })}</text>`,
104
- )
105
- .join('')}${labels
106
- .map((label, index) =>
107
- index % every === 0
108
- ? `<text x="${x(index)}" y="${top + height + 20}" text-anchor="middle" class="ct">${escaped(shorten({ value: label, max: 8 }))}</text>`
109
- : '',
110
- )
111
- .join('')}${series
112
- .map((s, index) => {
113
- const points = s.values.slice(0, labels.length);
114
- const path = points.map((value, i) => `${i === 0 ? 'M' : 'L'}${x(i)} ${y(value)}`).join('');
115
- const last = points.at(-1) ?? 0;
116
-
117
- return `<g><path d="${path}" fill="none" stroke="var(--s${index + 1})" stroke-width="2.5" stroke-linejoin="round" stroke-linecap="round"/>${points
118
- .map(
119
- (value, i) =>
120
- `<circle cx="${x(i)}" cy="${y(value)}" r="4.5" fill="var(--s${index + 1})" class="cring"><title>${escaped(s.name)}, ${escaped(labels[i] ?? '')}: ${formatNumber({ value })}${escaped(opts.chart.unit ?? '')}</title></circle>`,
121
- )
122
- .join(
123
- '',
124
- )}<text x="${VIEW_WIDTH - right + 8}" y="${(labelY.get(index) ?? y(last)) + 4}" class="cv">${escaped(shorten({ value: s.name, max: 8 }))}</text></g>`;
125
- })
126
- .join('')}</svg>`;
127
- };
128
-
129
- const SLOTS = ['var(--s1)', 'var(--s2)', 'var(--s3)', 'var(--s4)', 'var(--s5)'];
91
+ const every = labels.length > 6 ? Math.ceil(labels.length / 6) : 1;
92
+ // The direct labels sit at the last point of each line; where two would touch, they are pushed apart by 15 px.
93
+ const ends = series
94
+ .map((s, index) => ({ index, y: y(s.values.slice(0, labels.length).at(-1) ?? 0) }))
95
+ .sort((a, b) => a.y - b.y);
130
96
 
131
- const donutColour = (opts: { index: number; state?: string }): string =>
132
- opts.state === undefined
133
- ? (SLOTS[opts.index] ?? 'var(--s5)')
134
- : `var(--${NodeStates.toneOf(opts.state)})`;
135
-
136
- const donutChart = (opts: { chart: Extract<TChart, { type: 'donut' }> }): string => {
137
- const { parts } = opts.chart;
138
- const total = parts.reduce((sum, part) => sum + part.value, 0) || 1;
139
- const radius = 54;
140
- const circumference = 2 * Math.PI * radius;
141
- let offset = 0;
142
- const segments = parts
143
- .map((part, index) => {
144
- const share = part.value / total;
145
- const length = Math.max(0, share * circumference - 3);
146
- const out = `<circle cx="80" cy="80" r="${radius}" fill="none" stroke="${donutColour({ index, state: part.state })}" stroke-width="22" stroke-dasharray="${length.toFixed(2)} ${(circumference - length).toFixed(2)}" stroke-dashoffset="${(-offset).toFixed(2)}" transform="rotate(-90 80 80)"><title>${escaped(part.label)}: ${formatNumber({ value: part.value })}${escaped(opts.chart.unit ?? '')}</title></circle>`;
147
-
148
- offset += share * circumference;
149
-
150
- return out;
151
- })
152
- .join('');
153
-
154
- return `<svg viewBox="0 0 160 160" class="donut-svg" role="img" aria-label="${escaped(opts.chart.title)}">${segments}<text x="80" y="82" text-anchor="middle" class="cbig">${formatNumber({ value: total })}</text><text x="80" y="100" text-anchor="middle" class="ct">${escaped(opts.chart.unit ?? 'total')}</text></svg>`;
155
- };
97
+ for (let at = 1; at < ends.length; at += 1) {
98
+ const previous = ends[at - 1];
99
+ const current = ends[at];
156
100
 
157
- const legend = (opts: { chart: TChart }): string => {
158
- const { chart } = opts;
101
+ if (previous !== undefined && current !== undefined && current.y - previous.y < 15) {
102
+ current.y = previous.y + 15;
103
+ }
104
+ }
159
105
 
160
- if (chart.type === 'donut') {
161
- const total = chart.parts.reduce((sum, part) => sum + part.value, 0) || 1;
106
+ const labelY = new Map(ends.map((end) => [end.index, end.y]));
162
107
 
163
- return `<ul class="clegend">${chart.parts
108
+ return `<svg viewBox="0 0 ${VIEW_WIDTH} ${top + height + 34}" role="img" aria-label="${escaped(opts.chart.title)}">${ticks
164
109
  .map(
165
- (part, index) =>
166
- `<li><i class="sw" ${part.state === undefined ? `data-s="${index + 1}"` : `data-t="${NodeStates.toneOf(part.state)}"`}></i><span>${escaped(part.label)}</span><b>${formatNumber({ value: part.value })}${escaped(chart.unit ?? '')}</b><em>${Math.round((part.value / total) * 100)}%</em></li>`,
110
+ (tick) =>
111
+ `<line x1="${left}" x2="${VIEW_WIDTH - right}" y1="${y(tick)}" y2="${y(tick)}" class="cgrid"/><text x="${left - 6}" y="${y(tick) + 4}" text-anchor="end" class="ct">${SpecCharts.formatNumber({ value: tick })}</text>`,
167
112
  )
168
- .join('')}</ul>`;
113
+ .join('')}${labels
114
+ .map((label, index) =>
115
+ index % every === 0
116
+ ? `<text x="${x(index)}" y="${top + height + 20}" text-anchor="middle" class="ct">${escaped(shorten({ value: label, max: 8 }))}</text>`
117
+ : '',
118
+ )
119
+ .join('')}${series
120
+ .map((s, index) => {
121
+ const points = s.values.slice(0, labels.length);
122
+ const path = points.map((value, i) => `${i === 0 ? 'M' : 'L'}${x(i)} ${y(value)}`).join('');
123
+ const last = points.at(-1) ?? 0;
124
+
125
+ return `<g><path d="${path}" fill="none" stroke="var(--s${index + 1})" stroke-width="2.5" stroke-linejoin="round" stroke-linecap="round"/>${points
126
+ .map(
127
+ (value, i) =>
128
+ `<circle cx="${x(i)}" cy="${y(value)}" r="4.5" fill="var(--s${index + 1})" class="cring"><title>${escaped(s.name)}, ${escaped(labels[i] ?? '')}: ${SpecCharts.formatNumber({ value })}${escaped(opts.chart.unit ?? '')}</title></circle>`,
129
+ )
130
+ .join(
131
+ '',
132
+ )}<text x="${VIEW_WIDTH - right + 8}" y="${(labelY.get(index) ?? y(last)) + 4}" class="cv">${escaped(shorten({ value: s.name, max: 8 }))}</text></g>`;
133
+ })
134
+ .join('')}</svg>`;
169
135
  }
170
136
 
171
- if (chart.type === 'line' && chart.series.length > 1) {
172
- return `<ul class="clegend row">${chart.series.map((s, index) => `<li><i class="sw" data-s="${index + 1}"></i><span>${escaped(s.name)}</span></li>`).join('')}</ul>`;
137
+ private static donutChart(opts: { chart: Extract<TChart, { type: 'donut' }> }): string {
138
+ const { parts } = opts.chart;
139
+ const total = parts.reduce((sum, part) => sum + part.value, 0) || 1;
140
+ const radius = 54;
141
+ const circumference = 2 * Math.PI * radius;
142
+ let offset = 0;
143
+ const segments = parts
144
+ .map((part, index) => {
145
+ const share = part.value / total;
146
+ const length = Math.max(0, share * circumference - 3);
147
+ const out = `<circle cx="80" cy="80" r="${radius}" fill="none" stroke="${donutColour({ index, state: part.state })}" stroke-width="22" stroke-dasharray="${length.toFixed(2)} ${(circumference - length).toFixed(2)}" stroke-dashoffset="${(-offset).toFixed(2)}" transform="rotate(-90 80 80)"><title>${escaped(part.label)}: ${SpecCharts.formatNumber({ value: part.value })}${escaped(opts.chart.unit ?? '')}</title></circle>`;
148
+
149
+ offset += share * circumference;
150
+
151
+ return out;
152
+ })
153
+ .join('');
154
+
155
+ return `<svg viewBox="0 0 160 160" class="donut-svg" role="img" aria-label="${escaped(opts.chart.title)}">${segments}<text x="80" y="82" text-anchor="middle" class="cbig">${SpecCharts.formatNumber({ value: total })}</text><text x="80" y="100" text-anchor="middle" class="ct">${escaped(opts.chart.unit ?? 'total')}</text></svg>`;
173
156
  }
174
157
 
175
- return '';
176
- };
158
+ private static legend(opts: { chart: TChart }): string {
159
+ const { chart } = opts;
160
+
161
+ if (chart.type === 'donut') {
162
+ const total = chart.parts.reduce((sum, part) => sum + part.value, 0) || 1;
163
+
164
+ return `<ul class="clegend">${chart.parts
165
+ .map(
166
+ (part, index) =>
167
+ `<li><i class="sw" ${part.state === undefined ? `data-s="${index + 1}"` : `data-t="${NodeStates.toneOf(part.state)}"`}></i><span>${escaped(part.label)}</span><b>${SpecCharts.formatNumber({ value: part.value })}${escaped(chart.unit ?? '')}</b><em>${Math.round((part.value / total) * 100)}%</em></li>`,
168
+ )
169
+ .join('')}</ul>`;
170
+ }
171
+
172
+ if (chart.type === 'line' && chart.series.length > 1) {
173
+ return `<ul class="clegend row">${chart.series.map((s, index) => `<li><i class="sw" data-s="${index + 1}"></i><span>${escaped(s.name)}</span></li>`).join('')}</ul>`;
174
+ }
175
+
176
+ return '';
177
+ }
177
178
 
178
- const tableView = (opts: { chart: TChart; chrome: TChrome }): string => {
179
- const { chart, chrome } = opts;
180
- const head =
181
- chart.type === 'line' ? ['', ...chart.series.map((s) => s.name)] : ['', chrome.value];
182
- const rows =
183
- chart.type === 'bar'
184
- ? chart.labels.map((label, index) => [
185
- label,
186
- formatNumber({ value: chart.values[index] ?? 0 }),
187
- ])
188
- : chart.type === 'line'
179
+ private static tableView(opts: { chart: TChart; chrome: TChrome }): string {
180
+ const { chart, chrome } = opts;
181
+ const head =
182
+ chart.type === 'line' ? ['', ...chart.series.map((s) => s.name)] : ['', chrome.value];
183
+ const rows =
184
+ chart.type === 'bar'
189
185
  ? chart.labels.map((label, index) => [
190
186
  label,
191
- ...chart.series.map((s) => formatNumber({ value: s.values[index] ?? 0 })),
187
+ SpecCharts.formatNumber({ value: chart.values[index] ?? 0 }),
192
188
  ])
193
- : chart.parts.map((part) => [part.label, formatNumber({ value: part.value })]);
189
+ : chart.type === 'line'
190
+ ? chart.labels.map((label, index) => [
191
+ label,
192
+ ...chart.series.map((s) => SpecCharts.formatNumber({ value: s.values[index] ?? 0 })),
193
+ ])
194
+ : chart.parts.map((part) => [part.label, SpecCharts.formatNumber({ value: part.value })]);
195
+
196
+ return `<details class="tv"><summary>${escaped(chrome.tableView)}</summary><div class="tw"><table><thead><tr>${head.map((cell) => `<th>${escaped(cell)}</th>`).join('')}</tr></thead><tbody>${rows.map((row) => `<tr>${row.map((cell) => `<td>${escaped(cell)}</td>`).join('')}</tr>`).join('')}</tbody></table></div></details>`;
197
+ }
194
198
 
195
- return `<details class="tv"><summary>${escaped(chrome.tableView)}</summary><div class="tw"><table><thead><tr>${head.map((cell) => `<th>${escaped(cell)}</th>`).join('')}</tr></thead><tbody>${rows.map((row) => `<tr>${row.map((cell) => `<td>${escaped(cell)}</td>`).join('')}</tr>`).join('')}</tbody></table></div></details>`;
196
- };
199
+ /** One chart as a figure: a title, the drawing, a legend when there is more than one thing to tell apart, and its data as a table. */
200
+ static render(opts: { chart: TChart; chrome: TChrome }): string {
201
+ const { chart } = opts;
202
+ const drawing =
203
+ chart.type === 'bar'
204
+ ? SpecCharts.barChart({ chart })
205
+ : chart.type === 'line'
206
+ ? SpecCharts.lineChart({ chart })
207
+ : SpecCharts.donutChart({ chart });
208
+
209
+ return `<figure class="chart ${chart.type}"><figcaption class="lab">${escaped(chart.title)}</figcaption><div class="cbody">${drawing}${SpecCharts.legend({ chart })}</div>${SpecCharts.tableView({ chart, chrome: opts.chrome })}</figure>`;
210
+ }
197
211
 
198
- /** One chart as a figure: a title, the drawing, a legend when there is more than one thing to tell apart, and its data as a table. */
199
- export const renderChart = (opts: { chart: TChart; chrome: TChrome }): string => {
200
- const { chart } = opts;
201
- const drawing =
202
- chart.type === 'bar'
203
- ? barChart({ chart })
204
- : chart.type === 'line'
205
- ? lineChart({ chart })
206
- : donutChart({ chart });
207
-
208
- return `<figure class="chart ${chart.type}"><figcaption class="lab">${escaped(chart.title)}</figcaption><div class="cbody">${drawing}${legend({ chart })}</div>${tableView({ chart, chrome: opts.chrome })}</figure>`;
209
- };
212
+ /** Total scores of a comparison as horizontal bars out of the maximum, the recommendation in the accent. */
213
+ static renderTotals(opts: {
214
+ names: string[];
215
+ totals: number[];
216
+ best: number;
217
+ max: number;
218
+ chrome: TChrome;
219
+ }): string {
220
+ const rowHeight = 34;
221
+ const plot = 150;
222
+
223
+ return `<svg viewBox="0 0 ${VIEW_WIDTH} ${opts.names.length * rowHeight + 6}" role="img" aria-label="${escaped(opts.chrome.total)}: ${opts.names.map((n, i) => `${escaped(n)} ${opts.totals[i]}`).join(', ')}">${opts.names
224
+ .map((name, index) => {
225
+ const y = index * rowHeight + 4;
226
+ const total = opts.totals[index] ?? 0;
227
+ const width = Math.max(2, Math.round((total / opts.max) * plot));
228
+ const isBest = index === opts.best;
229
+
230
+ return `<g><title>${escaped(name)}: ${total} ${escaped(opts.chrome.outOf)} ${opts.max}</title><text x="0" y="${y + 19}" class="ct${isBest ? ' strong' : ''}">${escaped(shorten({ value: name, max: 18 }))}</text><rect x="120" y="${y + 5}" width="${plot}" height="20" rx="4" class="ctrack"/><path d="${barPath({ x: 120, y: y + 5, width, height: 20 })}" fill="${isBest ? 'var(--accent)' : 'var(--muted)'}" opacity="${isBest ? 1 : 0.6}"/><text x="${120 + width + 6}" y="${y + 20}" class="cv">${total}</text></g>`;
231
+ })
232
+ .join('')}</svg>`;
233
+ }
210
234
 
211
- /** Total scores of a comparison as horizontal bars out of the maximum, the recommendation in the accent. */
212
- export const renderTotals = (opts: {
213
- names: string[];
214
- totals: number[];
215
- best: number;
216
- max: number;
217
- chrome: TChrome;
218
- }): string => {
219
- const rowHeight = 34;
220
- const plot = 150;
221
-
222
- return `<svg viewBox="0 0 ${VIEW_WIDTH} ${opts.names.length * rowHeight + 6}" role="img" aria-label="${escaped(opts.chrome.total)}: ${opts.names.map((n, i) => `${escaped(n)} ${opts.totals[i]}`).join(', ')}">${opts.names
223
- .map((name, index) => {
224
- const y = index * rowHeight + 4;
225
- const total = opts.totals[index] ?? 0;
226
- const width = Math.max(2, Math.round((total / opts.max) * plot));
227
- const isBest = index === opts.best;
228
-
229
- return `<g><title>${escaped(name)}: ${total} ${escaped(opts.chrome.outOf)} ${opts.max}</title><text x="0" y="${y + 19}" class="ct${isBest ? ' strong' : ''}">${escaped(shorten({ value: name, max: 18 }))}</text><rect x="120" y="${y + 5}" width="${plot}" height="20" rx="4" class="ctrack"/><path d="${barPath({ x: 120, y: y + 5, width, height: 20 })}" fill="${isBest ? 'var(--acc)' : 'var(--mut)'}" opacity="${isBest ? 1 : 0.6}"/><text x="${120 + width + 6}" y="${y + 20}" class="cv">${total}</text></g>`;
230
- })
231
- .join('')}</svg>`;
232
- };
235
+ static stateIcon(opts: { state: string; size?: number }): string {
236
+ return IconSet.iconSvg({ name: NodeStates.iconOf(opts.state), size: opts.size });
237
+ }
233
238
 
234
- export const stateIcon = (opts: { state: string; size?: number }): string =>
235
- iconSvg({ name: NodeStates.iconOf(opts.state), size: opts.size });
239
+ /** 1234567 as 1,234,567 and 0.5 as 0.5: no locale, so the page reads the same everywhere. */
240
+ static formatNumber(opts: { value: number }): string {
241
+ const rounded = Math.round(opts.value * 100) / 100;
242
+ const [whole = '0', fraction] = String(Math.abs(rounded)).split('.');
243
+ const grouped = whole.replace(/\B(?=(\d{3})+(?!\d))/g, ',');
244
+
245
+ return `${rounded < 0 ? '-' : ''}${grouped}${fraction === undefined ? '' : `.${fraction}`}`;
246
+ }
247
+ }
@@ -0,0 +1,31 @@
1
+ /**
2
+ * The look of the compare view, the sources and the terms. Colours come from the page's tokens only. An arrow that only the
3
+ * second version has is heavy and solid, one that only the first has is dotted, a shared one is plain: the line style and a
4
+ * word tell them apart, never the colour. Appended after the page's own stylesheet, so these rules win on equal weight.
5
+ */
6
+ export const COMPARE_CSS = `.edge.added path{stroke:var(--ink);stroke-width:4.5}
7
+ .edge.added text{fill:var(--ink);font-weight:700}
8
+ .edge.removed path{stroke-dasharray:1 7;stroke-linecap:round;stroke-width:3}
9
+ .legend .edge.added path{stroke-width:4.5}
10
+ .legend .edge.removed path{stroke-width:3}
11
+ .cmp-key{margin-top:18px}
12
+ .path.cmp .cg{margin:22px 0 8px;color:var(--ink);font:650 15px/1.3 var(--font)}
13
+ .path.cmp .cg:first-child{margin-top:0}
14
+ .path.cmp .cg.added{padding-left:10px;border-left:4px solid var(--ink)}
15
+ .path.cmp .cg.removed{padding-left:10px;border-left:3px dotted var(--ink)}
16
+ .path.cmp ol{margin:0;padding:0}
17
+ .verb.added{border:2px solid var(--ink);color:var(--ink);font-weight:600}
18
+ .verb.removed{border:2px dotted var(--ink);color:var(--ink)}
19
+ .src{font:500 13px/1.5 var(--code);color:var(--muted);overflow-wrap:anywhere}
20
+ .path-detail .src,.explain .src{display:block;margin-top:4px}
21
+ .srcs{border-top:1px solid var(--line)}
22
+ .srcs li{display:grid;grid-template-columns:minmax(0,4fr) minmax(0,2fr);gap:6px 36px;align-items:baseline;padding:18px 0;border-bottom:1px solid var(--line)}
23
+ .srcs .src{color:var(--ink);font-size:14px}
24
+ .srcs .by{color:var(--body);font-size:15.5px}
25
+ .terms{display:grid;grid-template-columns:repeat(auto-fit,minmax(250px,1fr));gap:2px;margin:0;border-radius:var(--radius);overflow:hidden}
26
+ .terms div{display:grid;align-content:start;padding:26px 26px 30px;background:var(--bg-soft)}
27
+ @supports (grid-template-rows:subgrid){.terms div{grid-template-rows:subgrid;grid-row-end:span 2}}
28
+ .terms dt{color:var(--ink);font-size:19px;font-weight:650;letter-spacing:-.02em;margin-bottom:10px}
29
+ .terms dd{margin:0;max-width:52ch;color:var(--body);font-size:16px}
30
+ @media (max-width:700px){.srcs li{grid-template-columns:minmax(0,1fr)}.terms div{padding:22px 22px 26px}}
31
+ `;
@@ -0,0 +1,196 @@
1
+ import { EdgeSides } from './compare-schema.ts';
2
+ import type { TCompare } from './compare-schema.ts';
3
+ import type { TChrome } from './constants.ts';
4
+ import type { IDrawing } from './diagrams.ts';
5
+ import { FigureLayout } from './layout.ts';
6
+ import { SpecSections } from './sections.ts';
7
+ import type { ISectionContext } from './sections.ts';
8
+ import { SourceRefs } from './sources.ts';
9
+
10
+ const escaped = (value: string): string => FigureLayout.escapeText({ value });
11
+
12
+ /** The two sides of an arrow that is not in both. */
13
+ const ADDED = 'added';
14
+ const REMOVED = 'removed';
15
+
16
+ type TCompareEdge = TCompare['edges'][number];
17
+
18
+ /** The compare view: two versions of one mechanism as one figure, the arrows that differ drawn and worded apart. */
19
+ export class CompareView {
20
+ /** The side an edge belongs to; absent means both. */
21
+ private static sideOf(opts: { edge: TCompareEdge }): string {
22
+ return opts.edge.in ?? EdgeSides.BOTH;
23
+ }
24
+
25
+ /** The class an arrow is drawn with: heavy for what only the second has, dotted for what only the first has. */
26
+ private static variantOf(opts: { edge: TCompareEdge }): string | undefined {
27
+ const side = CompareView.sideOf(opts);
28
+
29
+ return side === EdgeSides.B ? ADDED : side === EdgeSides.A ? REMOVED : undefined;
30
+ }
31
+
32
+ /** The words that tell a changed arrow from a shared one: a sign and who has it alone. Never colour alone. */
33
+ private static wordOf(opts: { compare: TCompare; chrome: TChrome; side: string }): string {
34
+ const { compare, chrome, side } = opts;
35
+
36
+ return side === EdgeSides.B
37
+ ? `+ ${chrome.onlyHere} ${compare.b}`
38
+ : `- ${chrome.onlyHere} ${compare.a}`;
39
+ }
40
+
41
+ /** A short line of an arrow in the figure: the sign and the verb, so the line style is never the only sign. */
42
+ private static signedLabel(opts: { edge: TCompareEdge }): string {
43
+ const variant = CompareView.variantOf(opts);
44
+
45
+ return variant === ADDED
46
+ ? `+ ${opts.edge.label}`
47
+ : variant === REMOVED
48
+ ? `- ${opts.edge.label}`
49
+ : opts.edge.label;
50
+ }
51
+
52
+ /** A line sample of one kind of arrow, drawn by the same rules as the arrows of the figure. */
53
+ private static swatch(opts: { variant: string }): string {
54
+ return `<svg class="lg" viewBox="0 0 44 12" aria-hidden="true"><g class="edge ${opts.variant}"><path d="M0 6H44"/></g></svg>`;
55
+ }
56
+
57
+ /** The figure: the flow's own grid drawing with the added and removed arrows as their own classes. */
58
+ private static svgOf(opts: { compare: TCompare; chrome: TChrome }): string {
59
+ const { compare, chrome } = opts;
60
+ const svg = FigureLayout.render({
61
+ flow: {
62
+ nodes: compare.nodes,
63
+ edges: compare.edges.map((edge) => ({
64
+ from: edge.from,
65
+ to: edge.to,
66
+ label: CompareView.signedLabel({ edge }),
67
+ ...(CompareView.variantOf({ edge }) === undefined
68
+ ? {}
69
+ : { variant: CompareView.variantOf({ edge }) }),
70
+ })),
71
+ steps: [],
72
+ },
73
+ });
74
+ // A function as the replacement: a string would read `$&`, `$'` and `` $` `` in the spec's text as patterns.
75
+ let named = svg.replace(
76
+ 'aria-label="flow"',
77
+ () => `aria-label="${escaped(chrome.compareView)}"`,
78
+ );
79
+
80
+ // A changed arrow says its words when it is hovered or read by a screen reader, with the verb after them.
81
+ for (const edge of compare.edges) {
82
+ const side = CompareView.sideOf({ edge });
83
+
84
+ if (side !== EdgeSides.BOTH) {
85
+ const name = escaped(`${edge.from}>${edge.to}`);
86
+ const word = escaped(`${CompareView.wordOf({ compare, chrome, side })}: ${edge.label}`);
87
+
88
+ named = named.replace(
89
+ `data-edge="${name}"><title>${escaped(CompareView.signedLabel({ edge }))}</title>`,
90
+ () => `data-edge="${name}"><title>${word}</title>`,
91
+ );
92
+ }
93
+ }
94
+
95
+ // The label of an arrow that runs straight down or up sits on the line, and a heavy line would run through it: beside it.
96
+ named = named.replace(
97
+ /(<path d="M(-?[\d.]+) -?[\d.]+L\2 -?[\d.]+"[^>]*\/><text x=")-?[\d.]+(" y="-?[\d.]+" )text-anchor="middle"/g,
98
+ (_match, before: string, x: string, after: string) =>
99
+ `${before}${Number(x) + 10}${after}text-anchor="start"`,
100
+ );
101
+
102
+ // The page script highlights and describes the flow's boxes by these names: the compare view is its own thing.
103
+ return named
104
+ .replaceAll(' data-node="', ' data-cn="')
105
+ .replaceAll(' data-edge="', ' data-ce="')
106
+ .replace(/ data-detail="[^"]*"/g, '');
107
+ }
108
+
109
+ /** What replaces the figure on a phone: the arrows in three groups, then the boxes that have more to say. */
110
+ private static listOf(opts: { compare: TCompare; chrome: TChrome }): string {
111
+ const { compare, chrome } = opts;
112
+ const names = new Map(compare.nodes.map((node) => [node.id, node.label]));
113
+ const nameOf = (id: string): string => escaped(names.get(id) ?? id);
114
+ const groups: { side: string; head: string; cls: string }[] = [
115
+ { side: EdgeSides.BOTH, head: chrome.inBoth, cls: 'same' },
116
+ {
117
+ side: EdgeSides.B,
118
+ head: CompareView.wordOf({ compare, chrome, side: EdgeSides.B }),
119
+ cls: ADDED,
120
+ },
121
+ {
122
+ side: EdgeSides.A,
123
+ head: CompareView.wordOf({ compare, chrome, side: EdgeSides.A }),
124
+ cls: REMOVED,
125
+ },
126
+ ];
127
+ const lists = groups
128
+ .map((group) => {
129
+ const edges = compare.edges.filter((edge) => CompareView.sideOf({ edge }) === group.side);
130
+
131
+ return edges.length === 0
132
+ ? ''
133
+ : `<p class="cg ${group.cls}">${escaped(group.head)}</p><ol>${edges
134
+ .map(
135
+ (edge) =>
136
+ `<li><b>${nameOf(edge.from)}</b><span class="verb ${group.cls}">${escaped(edge.label)}</span><b>${nameOf(edge.to)}</b></li>`,
137
+ )
138
+ .join('')}</ol>`;
139
+ })
140
+ .join('');
141
+ const details = compare.nodes
142
+ .filter((node) => node.sublabel !== undefined || node.source !== undefined)
143
+ .map(
144
+ (node) =>
145
+ `<li><b>${escaped(node.label)}</b>${node.sublabel === undefined ? '' : escaped(node.sublabel)}${node.source === undefined ? '' : SourceRefs.html({ source: node.source })}</li>`,
146
+ )
147
+ .join('');
148
+
149
+ return `<div class="path cmp">${lists}</div>${details === '' ? '' : `<ul class="path-detail">${details}</ul>`}`;
150
+ }
151
+
152
+ /** The drawing, the width it needs, and what stands in for it: a key on wide screens, the grouped list on a phone. */
153
+ static drawing(opts: { compare: TCompare; chrome: TChrome }): IDrawing {
154
+ const { compare, chrome } = opts;
155
+ const key = [
156
+ { variant: 'main', word: chrome.inBoth },
157
+ { variant: ADDED, word: CompareView.wordOf({ compare, chrome, side: EdgeSides.B }) },
158
+ { variant: REMOVED, word: CompareView.wordOf({ compare, chrome, side: EdgeSides.A }) },
159
+ ]
160
+ .map(
161
+ (item) =>
162
+ `<li>${CompareView.swatch({ variant: item.variant })}<span>${escaped(item.word)}</span></li>`,
163
+ )
164
+ .join('');
165
+
166
+ return {
167
+ svg: CompareView.svgOf(opts),
168
+ width: FigureLayout.figureWidth({
169
+ cols: Math.max(...compare.nodes.map((node) => node.col)) + 1,
170
+ }),
171
+ fallback: `<ul class="legend cmp-key">${key}</ul>${CompareView.listOf(opts)}`,
172
+ };
173
+ }
174
+
175
+ /** The `compare` part of the page, after the flow and the architecture. */
176
+ static section(opts: { ctx: ISectionContext }): string {
177
+ const { compare } = opts.ctx.spec;
178
+ const { chrome } = opts.ctx;
179
+
180
+ if (compare === undefined) {
181
+ return '';
182
+ }
183
+
184
+ const count = (side: string): number =>
185
+ compare.edges.filter((edge) => CompareView.sideOf({ edge }) === side).length;
186
+ const caption =
187
+ compare.caption ??
188
+ `${CompareView.wordOf({ compare, chrome, side: EdgeSides.B })} (${count(EdgeSides.B)}), ${CompareView.wordOf({ compare, chrome, side: EdgeSides.A })} (${count(EdgeSides.A)})`;
189
+
190
+ return SpecSections.section({
191
+ id: 'compare',
192
+ title: chrome.compareView,
193
+ body: `<figure class="kfig">${SpecSections.figure({ ctx: opts.ctx, drawing: CompareView.drawing({ compare, chrome }) })}<figcaption>${escaped(caption)}</figcaption></figure>`,
194
+ });
195
+ }
196
+ }