@whzxc/agent-design-gallery 0.14.0 → 0.15.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 (64) hide show
  1. package/README.md +26 -16
  2. package/package.json +1 -1
  3. package/public/access.css +15 -2
  4. package/public/app.js +708 -483
  5. package/public/arrangement-worker.js +7 -7
  6. package/public/arrangement.js +35 -30
  7. package/public/assets.js +60 -38
  8. package/public/auth.js +59 -4
  9. package/public/boards.js +124 -0
  10. package/public/comment-anchors.js +50 -0
  11. package/public/comments.css +400 -0
  12. package/public/comments.js +1106 -0
  13. package/public/context-menu.js +97 -0
  14. package/public/frame-identity.js +26 -2
  15. package/public/hub.css +25 -3
  16. package/public/hub.html +10 -2
  17. package/public/hub.js +127 -23
  18. package/public/icons.js +2 -0
  19. package/public/index.html +13 -9
  20. package/public/instance-actions.js +9 -2
  21. package/public/layout.js +156 -86
  22. package/public/selection.js +1 -1
  23. package/public/style.css +74 -152
  24. package/public/switcher.css +5 -4
  25. package/public/switcher.js +109 -34
  26. package/public/token-catalog.js +8 -3
  27. package/public/tokens.css +14 -1
  28. package/public/view-route.js +0 -1
  29. package/src/boards/board.mjs +30 -0
  30. package/src/boards/token-board.mjs +196 -0
  31. package/src/cli-output.mjs +8 -5
  32. package/src/cli.mjs +49 -29
  33. package/src/comments.mjs +293 -0
  34. package/src/http.mjs +2 -3
  35. package/src/hub/project-link.mjs +41 -0
  36. package/src/hub/registry.mjs +5 -0
  37. package/src/hub.mjs +14 -10
  38. package/src/link.mjs +13 -1
  39. package/src/server.mjs +57 -93
  40. package/src/service.mjs +46 -12
  41. package/src/toolkit/arch.mjs +3 -2
  42. package/src/toolkit/asset-rules.mjs +24 -1
  43. package/src/toolkit/build-worker.mjs +6 -2
  44. package/src/toolkit/build.mjs +4 -2
  45. package/src/toolkit/commands.mjs +12 -7
  46. package/{public/review.js → src/toolkit/diff-document.mjs} +137 -43
  47. package/src/toolkit/diff-inputs.mjs +66 -30
  48. package/src/toolkit/diff.mjs +181 -39
  49. package/src/toolkit/impact-selection.mjs +25 -10
  50. package/src/toolkit/impact.mjs +32 -12
  51. package/src/toolkit/move-pairing.mjs +140 -0
  52. package/src/toolkit/project-index.mjs +2 -2
  53. package/src/toolkit/results.mjs +1 -1
  54. package/src/toolkit/review-document.mjs +435 -0
  55. package/src/toolkit/review-groups.mjs +29 -0
  56. package/src/toolkit/review-observation.mjs +131 -0
  57. package/src/toolkit/review-sheet.mjs +117 -0
  58. package/src/toolkit/review-specimens.mjs +60 -0
  59. package/src/toolkit/review.mjs +140 -0
  60. package/src/toolkit/runtime.mjs +1 -1
  61. package/src/toolkit/theme.mjs +16 -0
  62. package/public/annotations.js +0 -816
  63. package/public/labels.js +0 -122
  64. package/src/annotations.mjs +0 -238
@@ -1,21 +1,61 @@
1
1
  import path from 'node:path';
2
+ import { createHash } from 'node:crypto';
2
3
  import { readFileSync } from 'node:fs';
3
4
  import { mkdir, rm, writeFile } from 'node:fs/promises';
4
5
  import { availableParallelism } from 'node:os';
5
6
  import { launch, loadFrame, browserTask, readyResources } from './browser.mjs';
6
7
  import { prepareDiffInputs } from './diff-inputs.mjs';
8
+ import { pairFrameMoves } from './move-pairing.mjs';
7
9
  import { currentHead } from './arch-git.mjs';
10
+ import { relative, sourceDirectories, sourceFeature } from './project.mjs';
8
11
  import { pixelComparator, imageDifference } from './pixel-diff.mjs';
9
12
  import { partContext, captureEvidence, capturePart, isolateParent, frameIdentity, comparisonIdentity } from './part-diff.mjs';
10
13
  import { commandFailure, cleanup, emptySelection } from './results.mjs';
11
14
  import { CliError, classifyError, asCliError, nextActions } from '../cli-output.mjs';
12
15
  import { withImpacted } from './impact-selection.mjs';
13
16
  import { resolveDiffPolicy } from './diff-policy.mjs';
14
- import { buildReview, reviewDocumentHtml } from '../../public/review.js';
17
+ import { buildReview, reviewDocumentHtml } from './diff-document.mjs';
18
+ import { resolveThemes, systemTheme } from './theme.mjs';
19
+ import { renderReviewSheet } from './review-sheet.mjs';
15
20
 
16
21
  const metadata = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
17
22
  const safeName = name => encodeURIComponent(name).replace(/\./g, '%2E');
18
23
  const classNames = ['imperceptible', 'antialiasing', 'boundary_bleed', 'bitmap_resampling', 'other'];
24
+ const allThemes = ['light', 'dark'];
25
+
26
+ /** Git owns direct changes; impact reasons own inherited cause sets when available. */
27
+ export function reviewChange(row, inputs, built, selection = null) {
28
+ const changed = new Set((inputs.changes ?? []).flatMap(change => [change.before, change.after]).filter(Boolean));
29
+ const sides = [inputs.before, inputs.after ?? inputs.before];
30
+ const own = [...changed].filter(name => sides.some(({ config }) => {
31
+ const design = path.relative(config.root, config.design).split(path.sep).join('/');
32
+ const relativeSource = path.posix.relative(design, row.source);
33
+ const feature = sourceFeature(relativeSource, sourceDirectories(config));
34
+ return name === row.source || feature !== relativeSource && name.startsWith(path.posix.join(design, feature) + '/');
35
+ }));
36
+ if (own.length) return { kind: 'direct', causes: own.sort() };
37
+ const causes = new Set();
38
+ if (selection) {
39
+ const facts = new Map(selection.facts.map(fact => [fact.id, fact]));
40
+ for (const group of selection.frames) {
41
+ if (group.source !== row.source || !group.frames.includes(row.frame)) continue;
42
+ for (const entry of group.rows) for (const reason of entry.reasons ?? []) {
43
+ const source = facts.get(reason.fact)?.source;
44
+ if (source && reason.scope !== 'support') causes.add(source);
45
+ }
46
+ }
47
+ } else {
48
+ for (const [index, side] of sides.entries()) {
49
+ const source = [built.before, built.after][index]?.get(row.source);
50
+ for (const dependency of source?.dependencies ?? []) {
51
+ const name = path.relative(side.config.root, dependency).split(path.sep).join('/');
52
+ if (changed.has(name)) causes.add(name);
53
+ }
54
+ }
55
+ for (const name of inputs.globalChanges ?? []) causes.add(name);
56
+ }
57
+ return { kind: 'inherited', causes: [...causes].sort() };
58
+ }
19
59
 
20
60
  function frameFailure(error, row, theme) {
21
61
  const failure = asCliError(error, 'RENDER_FAILED');
@@ -23,13 +63,18 @@ function frameFailure(error, row, theme) {
23
63
  return failure;
24
64
  }
25
65
 
26
- async function capturePair(browser, row, theme, scale, context) {
66
+ async function capturePair(browser, row, theme, scale, context, cachedTheme) {
27
67
  const captures = { before: null, after: null };
28
68
  let page;
29
69
  try {
30
70
  for (const side of ['before', 'after']) {
31
71
  if (!row[side]) continue;
32
72
  page ??= await browserTask(browser, () => browser.newPage({ deviceScaleFactor: scale, locale: 'en-US', timezoneId: 'UTC' }));
73
+ if (!context?.targets.has(frameIdentity(row)) && cachedTheme?.has(row[side])) {
74
+ captures[side] = cachedTheme.get(row[side]);
75
+ cachedTheme.delete(row[side]);
76
+ continue;
77
+ }
33
78
  await loadFrame(page, row[side], theme);
34
79
  captures[side] = await browserTask(browser, async () => {
35
80
  await page.evaluate(readyResources);
@@ -52,6 +97,36 @@ async function capturePair(browser, row, theme, scale, context) {
52
97
  }
53
98
  }
54
99
 
100
+ // Normalize decoded screenshot pixels before hashing so PNG encoding does not affect matching.
101
+ async function renderFingerprints(browser, candidates, theme, scale, cachedTheme, concurrency) {
102
+ const fingerprints = new Map();
103
+ for (let start = 0; start < candidates.length; start += concurrency) {
104
+ const results = await Promise.allSettled(candidates.slice(start, start + concurrency).map(async row => {
105
+ const pair = await capturePair(browser, row, theme, scale, null);
106
+ const frame = row.before ?? row.after, capture = pair.before ?? pair.after;
107
+ let failure;
108
+ try {
109
+ const pixels = await browserTask(browser, () => pair.page.evaluate(async base64 => {
110
+ const image = new Image();
111
+ image.src = 'data:image/png;base64,' + base64;
112
+ await image.decode();
113
+ const canvas = document.createElement('canvas');
114
+ canvas.width = image.naturalWidth;
115
+ canvas.height = image.naturalHeight;
116
+ canvas.getContext('2d', { colorSpace: 'srgb' }).drawImage(image, 0, 0);
117
+ return canvas.toDataURL('image/png');
118
+ }, capture.png.toString('base64')));
119
+ cachedTheme.set(frame, capture);
120
+ fingerprints.set(row, createHash('sha256').update(JSON.stringify(capture.size)).update(pixels).digest('hex'));
121
+ } catch (error) { failure = frameFailure(error, row, theme); throw failure; }
122
+ finally { await cleanup(() => pair.page.close(), failure); }
123
+ }));
124
+ const failed = results.find(result => result.status === 'rejected');
125
+ if (failed) throw failed.reason;
126
+ }
127
+ return fingerprints;
128
+ }
129
+
55
130
  async function comparePair(browser, pair, thresholds, context) {
56
131
  try {
57
132
  return await browserTask(browser, async () => {
@@ -79,11 +154,18 @@ async function comparePair(browser, pair, thresholds, context) {
79
154
  } catch (error) { throw frameFailure(error, pair.row, pair.theme); }
80
155
  }
81
156
 
157
+ function revisionReasons(pair) {
158
+ const before = pair.before?.size, after = pair.after?.size;
159
+ const reasons = [];
160
+ if (before && after && Object.keys(before).some(key => before[key] !== after[key])) reasons.push('size_changed');
161
+ if (!pair.parent && pair.pixels.differentPixels) reasons.push('pixels_changed');
162
+ return reasons;
163
+ }
164
+
82
165
  async function writePair(output, pair, thresholds, reviewImages) {
83
166
  const { row, theme } = pair;
84
- const directory = path.join(output, row.support ? 'support' : 'frames', ...row.source.split('/').map(safeName), safeName(row.frame), theme);
85
- await mkdir(directory, { recursive: true });
86
- const paths = {
167
+ const directory = output && path.join(output, row.support ? 'support' : 'frames', ...row.source.split('/').map(safeName), safeName(row.frame), theme);
168
+ const paths = directory ? {
87
169
  before: pair.before ? path.join(directory, 'before.png') : null,
88
170
  after: pair.after ? path.join(directory, 'after.png') : null,
89
171
  difference: path.join(directory, 'difference.png'),
@@ -92,24 +174,27 @@ async function writePair(output, pair, thresholds, reviewImages) {
92
174
  parentCurrentSnapshot: pair.snapshots ? path.join(directory, 'parent-current.snapshot.json') : null,
93
175
  report: path.join(directory, 'comparison.json'), parentIsolated: pair.isolated ? path.join(directory, 'parent-isolated.png') : null,
94
176
  bleedMask: pair.bleedMask ? path.join(directory, 'bleed-mask.png') : null,
95
- };
177
+ } : null;
96
178
  const beforeSize = pair.before?.size ?? null, afterSize = pair.after?.size ?? null;
97
179
  const reasons = [];
98
- if (!pair.parent && row.status !== 'matched') reasons.push(row.status);
180
+ if (!pair.parent && row.status !== 'matched' && row.status !== 'moved') reasons.push(row.status);
99
181
  if (row.matchKind === 'renamed_or_unknown') reasons.push('renamed_or_unknown');
100
- if (beforeSize && afterSize && Object.keys(beforeSize).some(key => beforeSize[key] !== afterSize[key])) reasons.push('size_changed');
182
+ reasons.push(...revisionReasons(pair));
101
183
  if (pair.parent) {
102
184
  if (pair.snapshots.findings.length) reasons.push('snapshot_mismatch');
103
185
  if (pair.parentChanged) reasons.push('parent_changed');
104
186
  if (pair.singleTheme) reasons.push('theme_coverage_incomplete');
105
187
  if (pair.pixels.classes.other.pixels) reasons.push('other_pixels');
106
188
  if (!pair.pixels.classes.antialiasing.withinThreshold || !pair.pixels.classes.bitmap_resampling.withinThreshold) reasons.push('threshold_exceeded');
107
- } else if (pair.pixels.differentPixels) reasons.push('pixels_changed');
189
+ }
108
190
  const ref = { source: row.source, frame: row.frame };
191
+ const beforeRef = row.previousSource ? { source: row.previousSource, frame: row.previousFrame } : ref;
109
192
  const comparison = {
110
193
  id: JSON.stringify([row.source, row.frame, theme, ...(row.support ? ['support'] : [])]), ...ref, theme,
111
- status: row.status, matchKind: row.matchKind, matchCandidates: row.matchCandidates,
112
- relation: pair.parent ? 'parent_crop' : 'revision', before: pair.parent?.ref ?? (pair.before ? ref : null), after: pair.after ? ref : null,
194
+ status: row.status, matchKind: row.matchKind, matchCandidates: row.matchCandidates, change: row.change,
195
+ ...(row.previousSource ? { previousSource: row.previousSource } : {}),
196
+ relation: pair.parent ? 'parent_crop' : 'revision',
197
+ before: pair.parent?.ref ?? (pair.before ? beforeRef : null), after: pair.after ? ref : null,
113
198
  beforeSize, afterSize, parent: pair.parent ?? null, snapshots: pair.snapshots ?? null, pixels: pair.pixels,
114
199
  verdict: reasons.length ? 'changed' : pair.parent ? 'structural' : 'identical', reasons,
115
200
  note: { before: row.before?.note ?? null, after: row.after?.note ?? null },
@@ -117,13 +202,15 @@ async function writePair(output, pair, thresholds, reviewImages) {
117
202
  metadata: { before: row.before ? { locale: row.before.locale ?? null, proposed: row.before.proposed ?? null, fixture: row.before.fixture ?? null, capture: row.before.capture ?? null } : null,
118
203
  after: row.after ? { locale: row.after.locale ?? null, proposed: row.after.proposed ?? null, fixture: row.after.fixture ?? null, capture: row.after.capture ?? null } : null }, paths,
119
204
  };
120
- if (!row.support) {
205
+ if (!row.support && row.status !== 'moved') {
121
206
  reviewImages.set(comparison.id, {
122
- before: pair.before ? `data:image/png;base64,${pair.before.png.toString('base64')}` : null,
123
- after: pair.after ? `data:image/png;base64,${pair.after.png.toString('base64')}` : null,
207
+ before: output && pair.before ? `data:image/png;base64,${pair.before.png.toString('base64')}` : null,
208
+ after: output && pair.after ? `data:image/png;base64,${pair.after.png.toString('base64')}` : null,
124
209
  difference: `data:image/png;base64,${pair.difference.toString('base64')}`,
125
210
  });
126
211
  }
212
+ if (!directory) return comparison;
213
+ await mkdir(directory, { recursive: true });
127
214
  await Promise.all([
128
215
  pair.before && writeFile(paths.before, pair.before.png),
129
216
  pair.after && writeFile(paths.after, pair.after.png),
@@ -137,17 +224,24 @@ async function writePair(output, pair, thresholds, reviewImages) {
137
224
  }
138
225
 
139
226
  /** Exact ordinary frames and evidence-backed structural part comparisons. */
140
- export async function diff(config, args = [], options = {}, { launchBrowser = launch, prepareInputs = prepareDiffInputs, log = console.log, clock, session, onReview } = {}) {
141
- if (options.impacted && !session) return withImpacted(config, args, options, 'diff', selected =>
142
- diff(config, args, options, { launchBrowser, prepareInputs, log, clock, session: selected, onReview }));
143
- const started = performance.now(), scale = Number(options.scale ?? 2), themeOption = options.theme ?? 'both';
227
+ export async function diff(config, args = [], options = {}, { launchBrowser = launch, prepareInputs = prepareDiffInputs, log = console.log, clock, session, onReview, readSystemTheme = systemTheme, renderSheet = renderReviewSheet, sheetTheme, reviewOnly = false } = {}) {
228
+ const started = performance.now(), scale = Number(options.scale ?? 2);
144
229
  if (!Number.isFinite(scale) || scale <= 0) throw new CliError('USAGE_INVALID', 'Invalid --scale; use a positive number.');
145
- if (!['both', 'light', 'dark'].includes(themeOption)) throw new CliError('USAGE_INVALID', 'Choose --theme=both, light, or dark.');
230
+ const themes = resolveThemes(options.theme, readSystemTheme);
231
+ sheetTheme ??= themes.length === 1 ? themes[0] : readSystemTheme();
232
+ options = { ...options, theme: themes.length === 2 ? 'both' : themes[0] };
146
233
  if (options['out-dir'] === '') throw new CliError('USAGE_INVALID', 'Set --out-dir to a directory.');
147
- const themes = themeOption === 'both' ? ['light', 'dark'] : [themeOption];
148
- const output = options['out-dir'] === undefined ? path.join(config.output, 'diff') : path.resolve(config.root, options['out-dir']);
234
+ if (options.impacted && !session) {
235
+ return withImpacted(config, args, options, 'diff', selected =>
236
+ diff(config, args, options, { launchBrowser, prepareInputs, log, clock, session: selected,
237
+ readSystemTheme, renderSheet, sheetTheme, onReview, reviewOnly }));
238
+ }
239
+ const output = reviewOnly ? null : path.resolve(config.root, options['out-dir'] ?? path.join(config.output, 'diff'));
149
240
  const timings = { prepareMs: 0, buildMs: 0, captureMs: 0, compareMs: 0, writeMs: 0, totalMs: 0 };
150
241
  const warnings = [], completed = [], reviewImages = new Map();
242
+ const hiddenMoveReasons = new Set(), pendingMoveComparisons = new Map();
243
+ const cachedCaptures = new Map(allThemes.map(theme => [theme, new Map()]));
244
+ const concurrency = Math.min(4, availableParallelism());
151
245
  const thresholds = config.diff?.thresholds ?? resolveDiffPolicy().thresholds;
152
246
  let inputs, browser, data, primary, context;
153
247
  const timed = async (name, work) => {
@@ -168,31 +262,44 @@ export async function diff(config, args = [], options = {}, { launchBrowser = la
168
262
  existingCoverage: !inputs.sources.length ? 'empty' : args.length || options.frame !== undefined || themes.length !== 2 ? 'partial' : 'full' },
169
263
  environment: { adg: metadata.version, node: process.version, platform: process.platform, arch: process.arch, chromium: null,
170
264
  ...metadata.dependencies, locale: 'en-US', timezone: 'UTC', ...inputs.environment, baseThresholds: inputs.before.config.diff.thresholds },
171
- impact: session?.selection ?? null, classifierVersion: 1, thresholds, comparisons: [], support: [], verdict: null, reasons: [],
265
+ impact: session?.selection ?? null, classifierVersion: 1, thresholds, comparisons: [], support: [], failures: [], verdict: null, reasons: [],
172
266
  summary: { sources: inputs.sources.length, frames: 0, comparisons: 0, supportComparisons: 0, isolationCaptures: 0,
173
- added: 0, removed: 0, matched: 0, identical: 0, structural: 0, changed: 0,
267
+ added: 0, removed: 0, moved: 0, matched: 0, identical: 0, structural: 0, changed: 0,
174
268
  classPixels: Object.fromEntries(classNames.map(name => [name, 0])) },
175
- review: { added: 0, removed: 0, changed: 0 },
269
+ review: { added: 0, removed: 0, moved: 0, changed: 0, direct: 0, inherited: 0, groups: [], movePairs: [], sheet: null },
176
270
  differencePalette: { equal: '#00000000', imperceptible: '#64748b', antialiasing: '#f59e0b', boundary_bleed: '#0ea5e9', bitmap_resampling: '#a855f7', other: '#ff00ff' }, reportPath: null, indexPath: null, timings,
177
271
  };
178
- await timed('writeMs', () => Promise.all(['frames', 'support', 'report.json', 'index.html'].map(entry =>
272
+ if (output) await timed('writeMs', () => Promise.all(['frames', 'support', 'report.json', 'index.html', 'review-sheet.png'].map(entry =>
179
273
  rm(path.join(output, entry), { recursive: true, force: true }))));
180
274
  if (session ? session.chosen.some(row => row.source.endsWith('.mmd') && session.themes.some(theme => session.scheduled(row, theme))) : inputs.sources.length) browser = await launchBrowser();
181
- const built = await timed('buildMs', () => inputs.buildFrames({ browser }));
275
+ const built = await timed('buildMs', () => inputs.buildFrames({ browser, deferParts: true }));
276
+ data.failures = built.failures ?? [];
182
277
  if (session) built.frames = built.frames.filter(row => themes.some(theme => session.scheduled(row, theme)));
278
+ const moveThemes = [...new Set([...themes, ...allThemes])];
279
+ built.frames = await pairFrameMoves(built.frames, inputs, async (candidates, theme) => {
280
+ browser ??= await launchBrowser();
281
+ return timed('captureMs', () => renderFingerprints(browser, candidates, theme, scale, cachedCaptures.get(theme), concurrency));
282
+ }, moveThemes);
283
+ if (themes.length === 1) {
284
+ const offThemeCaptures = cachedCaptures.get(moveThemes[1]);
285
+ const pairedFrames = new Set(built.frames.filter(row => row.previousSource).flatMap(row => [row.before, row.after]));
286
+ for (const frame of offThemeCaptures.keys()) if (!pairedFrames.has(frame)) offThemeCaptures.delete(frame);
287
+ }
288
+ if (built.prepareParts) await timed('buildMs', built.prepareParts);
289
+ for (const row of [...built.frames, ...built.support]) row.change ??= reviewChange(row, inputs, built, session?.selection);
183
290
  context = partContext(built, inputs, scale, themes, clock);
184
291
  for (const warning of inputs.warnings) if (!warnings.includes(warning)) warnings.push(warning);
185
292
  data.summary.frames = built.frames.length;
186
293
  for (const row of built.frames) data.summary[row.status]++;
187
- if (!built.frames.length && (!session || !session.selection.coverage.expectedRows)) emptySelection(warnings);
294
+ if (!built.frames.length && !data.failures.length && (!session || !session.selection.coverage.expectedRows)) emptySelection(warnings);
188
295
  else if (built.frames.length) browser ??= await launchBrowser();
189
296
  if (browser) data.environment.chromium = browser.version();
190
297
  const selectedOrder = new Map(built.frames.flatMap(row => themes.map(theme => comparisonIdentity(row, theme))).map((key, index) => [key, index]));
191
298
  const supportKeys = new Set(built.support.map(frameIdentity));
192
299
  const ordinary = [...built.frames.filter(row => !row.parentRow), ...built.support.map(row => ({ ...row, support: true }))];
193
- const ordinaryJobs = ordinary.flatMap(row => themes.filter(theme => !session || row.support || session.scheduled(row, theme)).map(theme => ({ row, theme })));
300
+ const ordinaryJobs = ordinary.flatMap(row => (row.previousSource ? moveThemes :
301
+ themes.filter(theme => !session || row.support || session.scheduled(row, theme))).map(theme => ({ row, theme })));
194
302
  const partJobs = built.frames.filter(row => row.parentRow).flatMap(row => themes.filter(theme => !session || session.scheduled(row, theme)).map(theme => ({ row, theme })));
195
- const concurrency = Math.min(4, availableParallelism());
196
303
  for (const jobs of [ordinaryJobs, partJobs]) for (let start = 0; start < jobs.length; start += concurrency) {
197
304
  const failures = [], openPairs = [];
198
305
  const phase = async (name, items, work) => {
@@ -207,9 +314,26 @@ export async function diff(config, args = [], options = {}, { launchBrowser = la
207
314
  const batch = jobs.slice(start, start + concurrency);
208
315
  openPairs.push(...await phase('captureMs', batch, job => job.row.parentRow
209
316
  ? browserTask(browser, () => capturePart(browser, job.row, job.theme, context)).catch(error => { throw frameFailure(error, job.row, job.theme); })
210
- : capturePair(browser, job.row, job.theme, scale, context)));
317
+ : capturePair(browser, job.row, job.theme, scale, context, cachedCaptures.get(job.theme))));
211
318
  const compared = await phase('compareMs', openPairs, pair => comparePair(browser, pair, thresholds, context));
212
- const rows = await phase('writeMs', compared, pair => writePair(output, pair, thresholds, reviewImages));
319
+ const selected = compared.flatMap(pair => {
320
+ const { row } = pair;
321
+ if (!row.previousSource) return [pair];
322
+ const pairs = pendingMoveComparisons.get(row) ?? [];
323
+ pairs.push(pair);
324
+ if (pairs.length < allThemes.length) { pendingMoveComparisons.set(row, pairs); return []; }
325
+ pendingMoveComparisons.delete(row);
326
+ if (pairs.every(item => revisionReasons(item).length === 0)) {
327
+ row.status = 'moved';
328
+ data.summary.matched--;
329
+ data.summary.moved++;
330
+ }
331
+ for (const item of pairs) if (!themes.includes(item.theme)) {
332
+ for (const reason of revisionReasons(item)) hiddenMoveReasons.add(reason);
333
+ }
334
+ return pairs.filter(item => themes.includes(item.theme));
335
+ });
336
+ const rows = await phase('writeMs', selected, pair => writePair(output, pair, thresholds, reviewImages));
213
337
  for (const row of rows) {
214
338
  context?.comparisons.set(comparisonIdentity(row, row.theme), row);
215
339
  if (supportKeys.has(frameIdentity(row))) { data.support.push(row); data.summary.supportComparisons++; }
@@ -233,6 +357,13 @@ export async function diff(config, args = [], options = {}, { launchBrowser = la
233
357
  throw failures[0].error;
234
358
  }
235
359
  }
360
+ if (output && options.impacted) await timed('writeMs', async () => {
361
+ await mkdir(output, { recursive: true });
362
+ browser ??= await launchBrowser();
363
+ const model = buildReview({ ...data, complete: !data.failures.length }, reviewImages, { label: config.name ?? path.basename(config.root) });
364
+ const designDirs = { before: relative(inputs.before.config, inputs.before.config.design), after: relative(config, config.design) };
365
+ data.review.sheet = await renderSheet(browser, model, sheetTheme, path.join(output, 'review-sheet.png'), completed, designDirs);
366
+ });
236
367
  } catch (error) {
237
368
  if (inputs) {
238
369
  if (error.message) error.message = inputs.translateDiagnostic(error.message);
@@ -247,10 +378,13 @@ export async function diff(config, args = [], options = {}, { launchBrowser = la
247
378
  }
248
379
  }
249
380
  if (!data) throw primary;
381
+ let sourceFailureOnly = !primary && data.failures.length > 0;
382
+ if (sourceFailureOnly) primary = commandFailure(new CliError('SOURCE_BUILD_FAILED',
383
+ `${new Set(data.failures.map(failure => failure.source)).size} source(s) could not be compared; review the source failures.`, { data }), data, warnings);
250
384
  data.complete = !primary;
251
385
  if (!primary) {
252
- data.verdict = data.summary.changed || data.support.some(row => row.verdict === 'changed') ? 'changed' : data.summary.structural ? 'structural' : 'identical';
253
- data.reasons = [...new Set([...completed, ...data.support].flatMap(row => row.reasons))];
386
+ data.verdict = data.summary.changed || hiddenMoveReasons.size || data.support.some(row => row.verdict === 'changed') ? 'changed' : data.summary.structural ? 'structural' : 'identical';
387
+ data.reasons = [...new Set([...completed, ...data.support].flatMap(row => row.reasons).concat([...hiddenMoveReasons]))];
254
388
  if (data.summary.structural && data.selection.existingCoverage !== 'full') {
255
389
  data.verdict = 'changed'; data.reasons.push('existing_coverage_incomplete');
256
390
  }
@@ -260,22 +394,30 @@ export async function diff(config, args = [], options = {}, { launchBrowser = la
260
394
  }
261
395
  }
262
396
  const reviewModel = buildReview(data, reviewImages, { label: config.name ?? path.basename(config.root) });
263
- data.review = reviewModel.counts;
397
+ data.review = { ...reviewModel.counts, movePairs: reviewModel.movePairs ?? [], groups: (reviewModel.groups ?? []).map(group => ({
398
+ causes: group.causes, frames: group.frames.map(({ source, frame }) => ({ source, frame })),
399
+ representative: { source: group.representative.source, frame: group.representative.frame },
400
+ outliers: group.outliers.map(({ source, frame }) => ({ source, frame })), medianArea: group.medianArea,
401
+ })), sheet: data.review.sheet };
264
402
  onReview?.(reviewModel);
265
403
  timings.totalMs = performance.now() - started;
266
- data.reportPath = path.join(output, 'report.json');
267
- data.indexPath = path.join(output, 'index.html');
268
- try {
404
+ if (output) try {
405
+ data.reportPath = path.join(output, 'report.json');
406
+ data.indexPath = path.join(output, 'index.html');
269
407
  await mkdir(output, { recursive: true });
270
408
  await writeFile(data.indexPath, reviewDocumentHtml(reviewModel));
271
409
  if (!session) await writeFile(data.reportPath, JSON.stringify(data, null, 2) + '\n');
272
410
  } catch (error) {
411
+ sourceFailureOnly = false;
273
412
  data.reportPath = null; data.indexPath = null; data.complete = false; data.verdict = null;
274
413
  if (primary) primary.warnings.push(classifyError(error).error);
275
414
  else primary = commandFailure(error, data, warnings);
276
415
  }
277
- if (primary) throw primary;
278
- if (!options.json) log(`${data.verdict}: ${data.review.added} added, ${data.review.removed} removed, ${data.review.changed} changed (${data.summary.frames} frames). ${data.indexPath}`);
416
+ if (primary) {
417
+ if (sourceFailureOnly) primary.partialSourceFailures = true;
418
+ throw primary;
419
+ }
420
+ if (!options.json) log(`${data.verdict}: ${data.review.added} added, ${data.review.removed} removed, ${data.review.moved} moved, ${data.review.changed} changed (${data.summary.frames} frames). ${data.indexPath}`);
279
421
  if (data.verdict === 'changed') throw new CliError('DIFF_FAILED', 'Design differences require review.', { data, warnings });
280
422
  return { data, warnings };
281
423
  }
@@ -5,12 +5,15 @@ import { groupImpactFrames } from './impact-output.mjs';
5
5
  import { commandFailure } from './results.mjs';
6
6
  import { mkdir, writeFile } from 'node:fs/promises';
7
7
  import path from 'node:path';
8
+ import { resolveThemes } from './theme.mjs';
8
9
 
9
10
  export const impactRowKey = (row, theme) => JSON.stringify([row.source, row.frame, theme]);
10
11
 
11
12
  /** Keep fresh proofs, captures and final generation validation in one owned operation. */
12
13
  export async function withImpacted(config, args, options, command, work) {
13
- if (typeof options.base !== 'string' || !options.base.trim() || options.frame === '' || options.theme !== undefined && !['both', 'light', 'dark'].includes(options.theme)) throw new CliError('USAGE_INVALID', 'Choose --impacted --base=<rev> and a valid frame/theme selection.');
14
+ const themes = resolveThemes(options.theme);
15
+ options = { ...options, theme: themes.length === 2 ? 'both' : themes[0] };
16
+ if (typeof options.base !== 'string' || !options.base.trim() || options.frame === '') throw new CliError('USAGE_INVALID', 'Choose --impacted --base=<rev> and a valid frame/theme selection.');
14
17
  let outcome, failure, selection, workMs = 0;
15
18
  const warnings = [];
16
19
  function discardProofs() {
@@ -25,10 +28,11 @@ export async function withImpacted(config, args, options, command, work) {
25
28
  const plan = await impact(config, { base: options.base, json: true, 'state-dir': options['state-dir'], 'out-dir': options['out-dir'], explain: options.explain }, {
26
29
  consume: async session => {
27
30
  const { rows, views, assessments, inputs, data } = session;
28
- const sources = await selectedSources(views[1].config, views[0].config, views[1].config.root, new Set(rows.map(row => row.source)), args);
29
- const themes = options.theme && options.theme !== 'both' ? [options.theme] : ['light', 'dark'];
31
+ const sources = await selectedSources(views[1].config, views[0].config, views[1].config.root,
32
+ new Set([...rows.map(row => row.source), ...data.failures.map(failure => failure.source)]), args);
33
+ const failures = data.failures.filter(failure => sources.includes(failure.source));
30
34
  const chosen = rows.filter(row => sources.includes(row.source) && (options.frame === undefined || row.frame === options.frame));
31
- if (options.frame !== undefined && !chosen.length) {
35
+ if (options.frame !== undefined && !chosen.length && !failures.length) {
32
36
  throw new CliError('FRAME_NOT_FOUND', `Unknown frame ${options.frame}; choose a frame present on either side.`);
33
37
  }
34
38
  const exclusions = { source_filter: 0, frame_filter: 0, theme_filter: 0, hypothetical_input: 0, not_checked: 0 };
@@ -59,17 +63,26 @@ export async function withImpacted(config, args, options, command, work) {
59
63
  const finalize = data => {
60
64
  const coverage = selection.coverage;
61
65
  coverage.renderedRows = command === 'diff' ? data.summary.comparisons + data.summary.supportComparisons : command === 'check' ? data.summary.evaluations : data.captures.length;
66
+ if (command === 'diff') {
67
+ // A revision comparison of a move covers both original impact rows.
68
+ const pairedRows = (data.comparisons ?? []).filter(row => row.previousSource).length;
69
+ coverage.renderedRows += pairedRows;
70
+ coverage.deletedRows -= pairedRows;
71
+ }
62
72
  const deleted = command === 'render' ? coverage.deletedRows : 0;
63
73
  coverage.uncoveredRows = Math.max(0, coverage.expectedRows - coverage.renderedRows - coverage.provenRows - deleted);
64
- coverage.scope = !coverage.expectedRows ? 'empty' : coverage.uncoveredRows || args.length || options.frame !== undefined || themes.length !== 2 ? 'partial' : 'full';
74
+ coverage.scope = failures.length ? 'partial' : !coverage.expectedRows ? 'empty' : coverage.uncoveredRows || args.length || options.frame !== undefined || themes.length !== 2 ? 'partial' : 'full';
65
75
  coverage.basis = command === 'check' ? 'selected' : coverage.renderedRows ? coverage.provenRows ? 'rendered_and_proven' : 'rendered' : coverage.provenRows ? 'proven' : 'selected';
66
76
  data.impact = selection;
67
77
  };
68
78
  const next = [{ argv: ['adg', command, ...(command === 'diff' ? [`--base=${options.base}`] : command === 'check' ? ['--read-only'] : []),
69
79
  ...(options.scale !== undefined && command !== 'check' ? [`--scale=${options.scale}`] : []), '--json'], reason: 'Evaluate the full project without impact filtering.' }];
70
80
  session.selection = selection; session.sources = sources; session.chosen = chosen; session.themes = themes; session.scheduled = scheduled;
71
- session.diffInputs = { ...inputs.session, sources, close: async () => {},
72
- buildFrames: async ({ browser }) => inputs.session.buildFrames({ browser, materialized: views.map(view => view.built),
81
+ session.diffInputs = { ...inputs.session, sources,
82
+ changes: inputs.changes.map(change => Object.fromEntries(['before', 'after'].map(side => [side,
83
+ change[side] === null ? null : path.posix.relative(inputs.projectPrefix || '.', change[side])]))),
84
+ close: async () => {},
85
+ buildFrames: async ({ browser, deferParts }) => inputs.session.buildFrames({ browser, deferParts, materialized: views.map(view => view.built), failures,
73
86
  frame: options.frame, sources: [...new Set(chosen.filter(row => themes.some(theme => scheduled(row, theme))).map(row => row.source))] }) };
74
87
  const workStarted = performance.now();
75
88
  try { outcome = await work(session); } catch (cause) { failure = cause; outcome = { data: cause.data, warnings: cause.warnings ?? [] }; }
@@ -79,21 +92,23 @@ export async function withImpacted(config, args, options, command, work) {
79
92
  if (selection.coverage.scope === 'partial') warnings.push({ code: 'IMPACT_COVERAGE_PARTIAL', message: 'Impact selection has partial frame/theme coverage.', next });
80
93
  if (!failure && !chosen.some(row => (command === 'diff' || row.after) && themes.some(theme => scheduled(row, theme)))) warnings.push({ code: 'IMPACT_NO_CHANGES', message: 'No capture or browser-evaluation jobs were scheduled.', next });
81
94
  }
82
- if (failure && !['CHECK_FAILED', 'DIFF_FAILED'].includes(failure.code)) throw failure;
95
+ if (failure && !['CHECK_FAILED', 'DIFF_FAILED'].includes(failure.code) && !(command === 'diff' && failure.partialSourceFailures === true)) throw failure;
83
96
  },
97
+ tolerateSourceFailures: command === 'diff',
84
98
  });
85
99
  warnings.push(...plan.warnings.filter(w => !['IMPACT_NO_CHANGES', 'IMPACT_NO_MATCH'].includes(w.code)));
86
- if (selection) selection.coverage.proofComplete = true;
100
+ if (selection) selection.coverage.proofComplete = !plan.data.failures.length;
87
101
  if (outcome?.data) outcome.data.timings = { ...outcome.data.timings, impactMs: plan.data.timings.totalMs - workMs, workMs, materializeMs: plan.data.timings.materializeMs, proofMs: plan.data.timings.proofMs, totalMs: plan.data.timings.totalMs };
88
102
  } catch (cause) {
89
103
  discardProofs();
104
+ if (failure) delete failure.partialSourceFailures;
90
105
  if (!outcome?.data) cause.data = null;
91
106
  failure = outcome?.data ? commandFailure(cause, outcome.data, warnings) : cause;
92
107
  }
93
108
  if (outcome) outcome.warnings = [...new Set([...outcome.warnings, ...warnings])];
94
109
  if (outcome?.data?.reportPath) {
95
110
  try { await mkdir(path.dirname(outcome.data.reportPath), { recursive: true }); await writeFile(outcome.data.reportPath, JSON.stringify(outcome.data, null, 2) + '\n'); }
96
- catch (cause) { discardProofs(); outcome.data.reportPath = null; if ('indexPath' in outcome.data) outcome.data.indexPath = null; failure = commandFailure(cause, outcome.data, outcome.warnings); }
111
+ catch (cause) { discardProofs(); outcome.data.reportPath = null; if ('indexPath' in outcome.data) outcome.data.indexPath = null; failure = commandFailure(cause, outcome.data, outcome.warnings); delete failure.partialSourceFailures; }
97
112
  }
98
113
  if (failure) { if (outcome?.data) failure = commandFailure(failure, outcome.data, outcome.warnings); throw failure; }
99
114
  return outcome;
@@ -3,7 +3,7 @@ import { readFile, realpath, stat } from 'node:fs/promises';
3
3
  import { CliError, nextActions } from '../cli-output.mjs';
4
4
  import { openProjectIndex } from './project-index.mjs';
5
5
  import { prepareImpactInputs, configInputFiles } from './impact-inputs.mjs';
6
- import { matchDiffFrames } from './diff-inputs.mjs';
6
+ import { matchDiffFrames, sourceFailure } from './diff-inputs.mjs';
7
7
  import { selectSources, relative } from './project.mjs';
8
8
  import { loadImplementationMap, implementationFiles } from './implementation-map.mjs';
9
9
  import { normalizeFileQuery, implementationScope } from './implementation-query.mjs';
@@ -42,7 +42,7 @@ function mappingBuild(facts) {
42
42
  }
43
43
 
44
44
  /** Candidate queries and operation-local fresh-input proofs for exact Git endpoints. */
45
- export async function impact(config, values, { log = console.log, openIndex = openProjectIndex, prepareInputs = prepareImpactInputs, consume } = {}) {
45
+ export async function impact(config, values, { log = console.log, openIndex = openProjectIndex, prepareInputs = prepareImpactInputs, consume, tolerateSourceFailures = false } = {}) {
46
46
  const started = performance.now(), themes = themesFor(values);
47
47
  const timings = { prepareMs: 0, indexMs: 0, materializeMs: 0, proofMs: 0, queryMs: 0, totalMs: 0 };
48
48
  const timed = async (name, work) => { const start = performance.now(); try { return await work(); } finally { timings[name] += performance.now() - start; } };
@@ -67,7 +67,7 @@ export async function impact(config, values, { log = console.log, openIndex = op
67
67
  data = { project: config.root, complete: false, query,
68
68
  before: inputs ? { kind: 'revision', sha: query.base.sha } : null,
69
69
  after: { kind: inputs?.after.revision ? 'revision' : 'working_tree', sha: inputs?.head ?? null },
70
- selection: { themes, explain: !!values.explain }, changes: [], facts: [], frames: [], mappingFindings: [], unresolvedInputs: [],
70
+ selection: { themes, explain: !!values.explain }, changes: [], facts: [], frames: [], failures: [], mappingFindings: [], unresolvedInputs: [],
71
71
  coverage: { inventory: 'incomplete', mapping: 'not_requested', expectedRows: 0, candidateRows: 0, directRows: 0, transitiveRows: 0,
72
72
  renderRows: 0, provenRows: 0, unassessedRows: 0, proofComplete: false,
73
73
  tokenScan: { reachableRows: 0, fullSheetRows: 0, fallbackReasons: [] } }, timings };
@@ -91,12 +91,22 @@ export async function impact(config, values, { log = console.log, openIndex = op
91
91
  return view;
92
92
  });
93
93
  const { index, config: current } = view;
94
+ const failed = new Set();
94
95
  if (inputs) await timed('materializeMs', async () => {
95
96
  const settled = await Promise.allSettled(index.inventory.tsx.map(async source => [source, await index.materialize(source)]));
96
- for (const result of settled) { if (result.status === 'rejected') throw result.reason; view.built.set(...result.value); }
97
+ for (const [position, result] of settled.entries()) {
98
+ if (result.status === 'fulfilled') view.built.set(...result.value);
99
+ else {
100
+ if (!tolerateSourceFailures) throw result.reason;
101
+ const source = index.inventory.tsx[position];
102
+ failed.add(source);
103
+ data.failures.push(sourceFailure(result.reason, source, side === 'before' ? 'base' : 'current', inputs.translate));
104
+ }
105
+ }
97
106
  });
98
107
  await timed('indexMs', async () => {
99
108
  for (const source of index.inventory.tsx) {
109
+ if (failed.has(source)) continue;
100
110
  const facts = await index.source(source, { tokens: query.kind === 'token' || query.kind === 'git', fresh: !!inputs });
101
111
  view.facts.set(source, facts);
102
112
  for (const frame of facts.tokenDependencies ?? []) for (const row of frame.themes) if (themes.includes(row.theme)) {
@@ -107,16 +117,26 @@ export async function impact(config, values, { log = console.log, openIndex = op
107
117
  }
108
118
  }
109
119
  for (const source of index.inventory.architecture) {
110
- const metadata = await index.architecture(source), file = path.join(current.root, source), sidecar = path.join(current.root, metadata.sidecar);
111
- await track(file); await track(sidecar);
112
- view.architecture.set(source, { source: await bytes(file), sidecar: await bytes(sidecar), tokens: view.tokenBytes, config: current });
113
- view.facts.set(source, { source, parts: [], imports: [], dependencies: [source, metadata.sidecar, relative(current, view.tokenFile)], frames: [{ name: 'default', parts: [] }] });
120
+ try {
121
+ const metadata = await index.architecture(source), file = path.join(current.root, source), sidecar = path.join(current.root, metadata.sidecar);
122
+ await track(file); await track(sidecar);
123
+ view.architecture.set(source, { source: await bytes(file), sidecar: await bytes(sidecar), tokens: view.tokenBytes, config: current });
124
+ view.facts.set(source, { source, parts: [], imports: [], dependencies: [source, metadata.sidecar, relative(current, view.tokenFile)], frames: [{ name: 'default', parts: [] }] });
125
+ } catch (error) {
126
+ if (!tolerateSourceFailures) throw error;
127
+ data.failures.push(sourceFailure(error, source, side === 'before' ? 'base' : 'current', inputs.translate));
128
+ }
114
129
  }
115
- view.graph = await index.relationships({ facts: view.facts, projectPaths: true });
130
+ view.graph = await index.relationships({ facts: view.facts, projectPaths: true, sources: index.inventory.tsx.filter(source => !failed.has(source)) });
116
131
  view.tokens = view.facts.size || query.kind === 'token' ? index.tokens() : [];
117
132
  if (query.kind === 'file' || query.kind === 'git') { view.map = await loadImplementationMap(current); await track(view.map.file); }
118
133
  });
119
134
  }
135
+ const failedSources = new Set(data.failures.map(failure => failure.source));
136
+ for (const view of views) for (const source of failedSources) {
137
+ view.facts.delete(source);
138
+ view.built.delete(source);
139
+ }
120
140
  const scan = data.coverage.tokenScan;
121
141
  scan.fallbackReasons.sort(compare);
122
142
  if (scan.fullSheetRows) warn('IMPACT_TOKEN_FALLBACK', `Token scan used the full sheet for ${scan.fullSheetRows} frame/theme inputs: ${scan.fallbackReasons.join(', ')}.`,
@@ -154,7 +174,7 @@ export async function impact(config, values, { log = console.log, openIndex = op
154
174
  async function mappings(view, indices, pathIndexes = []) {
155
175
  if (!view.map.present) { data.coverage.mapping = data.coverage.mapping === 'stale' ? 'stale' : 'absent'; unresolved(view.map.source, 'mapping_absent'); return; }
156
176
  if (data.coverage.mapping === 'not_requested') data.coverage.mapping = 'valid';
157
- const validated = await view.index.mappings({ map: view.map, mappingIndices: indices,
177
+ const validated = await view.index.mappings({ map: view.map, mappingIndices: indices, selected: failedSources.size ? [...view.facts.keys()] : undefined,
158
178
  getBuild: source => {
159
179
  const facts = view.facts.get(source);
160
180
  // Mapping validators expect design-relative marker provenance.
@@ -333,7 +353,7 @@ export async function impact(config, values, { log = console.log, openIndex = op
333
353
  }
334
354
  });
335
355
  timings.queryMs = Math.max(0, timings.queryMs - (timings.proofMs - proofBeforeQuery));
336
- data.coverage.inventory = 'complete';
356
+ data.coverage.inventory = data.failures.length ? 'incomplete' : 'complete';
337
357
  if (data.unresolvedInputs.length || data.mappingFindings.length) warn('IMPACT_MAPPING_INCOMPLETE', 'Some implementation mappings are absent, unmatched or stale; inspect the resolvable targets and findings.', checkNext('Repair implementation.json and its reported locators before repeating the query.'));
338
358
  if (!data.frames.length) {
339
359
  const observed = query.kind === 'token' ? { token: query.tokens[0], theme: values.theme } : query.kind === 'file' ? { file: query.input, theme: values.theme } : null;
@@ -352,7 +372,7 @@ export async function impact(config, values, { log = console.log, openIndex = op
352
372
  try { await cleanup(() => view.index.close(), primary); } catch (cause) { primary = data ? commandFailure(cause, data, warnings) : cause; }
353
373
  }
354
374
  if (!primary) {
355
- try { await verifyGeneration(); data.coverage.proofComplete = !!inputs; }
375
+ try { await verifyGeneration(); data.coverage.proofComplete = !!inputs && !data.failures.length; }
356
376
  catch (cause) {
357
377
  if (cause.code === 'OWNER_INDEX_CHANGED') cause = new CliError('IMPACT_INPUT_CHANGED', cause.message, { cause });
358
378
  if (inputs) cause.message = inputs.translate(cause.message);