hauntview 0.0.0-stage → 0.0.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +358 -2
- package/VERSION +1 -0
- package/dist/cli.js +8184 -0
- package/package.json +120 -4
- package/scripts/postinstall.mjs +47 -0
- package/src/core/browser-launch.ts +60 -0
- package/src/core/browser-pool.ts +267 -0
- package/src/core/concurrency-resolver.ts +154 -0
- package/src/core/finding-classifier.ts +346 -0
- package/src/core/index.ts +8 -0
- package/src/core/profile-manager.ts +499 -0
- package/src/core/report-store.ts +117 -0
- package/src/core/screenshot-manager.ts +312 -0
- package/src/core/system-capability.ts +161 -0
- package/src/core/visual-diff.ts +230 -0
- package/src/engine.ts +473 -0
- package/src/profiles/accessibility-cognitive.ts +261 -0
- package/src/profiles/accessibility-keyboard.ts +225 -0
- package/src/profiles/accessibility-screenreader.ts +243 -0
- package/src/profiles/accessibility-visual.ts +257 -0
- package/src/profiles/broken-links.ts +261 -0
- package/src/profiles/browser-edge.ts +192 -0
- package/src/profiles/browser-firefox.ts +254 -0
- package/src/profiles/browser-legacy.ts +213 -0
- package/src/profiles/console-errors.ts +192 -0
- package/src/profiles/desktop-4k.ts +273 -0
- package/src/profiles/desktop.ts +192 -0
- package/src/profiles/font-failure.ts +148 -0
- package/src/profiles/form-resilience.ts +285 -0
- package/src/profiles/i18n-cjk.ts +218 -0
- package/src/profiles/i18n-mixed.ts +255 -0
- package/src/profiles/i18n-rtl.ts +236 -0
- package/src/profiles/image-failure.ts +178 -0
- package/src/profiles/index.ts +42 -0
- package/src/profiles/js-disabled.ts +179 -0
- package/src/profiles/mobile.ts +175 -0
- package/src/profiles/network-resilience.ts +208 -0
- package/src/profiles/offline.ts +165 -0
- package/src/profiles/performance.ts +244 -0
- package/src/profiles/reduced-motion.ts +144 -0
- package/src/profiles/security-hygiene.ts +206 -0
- package/src/profiles/tablet.ts +176 -0
- package/src/reports/factory.ts +56 -0
- package/src/reports/html-generator.ts +1105 -0
- package/src/reports/index.ts +9 -0
- package/src/reports/markdown-generator.ts +349 -0
- package/src/reports/types.ts +34 -0
- package/src/reports/zip-generator.ts +85 -0
- package/src/types/contracts.ts +238 -0
- package/src/types/finding-utils.ts +121 -0
- package/src/types/index.ts +8 -0
- package/src/types/profiles.ts +175 -0
- package/src/types/results.ts +135 -0
- package/src/version.ts +5 -0
|
@@ -0,0 +1,312 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* ScreenshotManager - Handles screenshot capture, storage, and comparison
|
|
3
|
+
* Manages screenshot metadata, hashing, and deduplication
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
import * as fs from 'fs/promises';
|
|
7
|
+
import * as path from 'path';
|
|
8
|
+
import * as crypto from 'crypto';
|
|
9
|
+
import { Page } from 'playwright';
|
|
10
|
+
import { PNG } from 'pngjs';
|
|
11
|
+
import { ScreenshotMetadata, Viewport } from '../types';
|
|
12
|
+
|
|
13
|
+
interface StoredScreenshot {
|
|
14
|
+
metadata: ScreenshotMetadata;
|
|
15
|
+
buffer: Buffer;
|
|
16
|
+
hash: string;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export class ScreenshotManager {
|
|
20
|
+
private screenshotDir: string;
|
|
21
|
+
private screenshots: Map<string, StoredScreenshot> = new Map();
|
|
22
|
+
private hashIndex: Map<string, string[]> = new Map(); // hash -> filenames
|
|
23
|
+
|
|
24
|
+
constructor(screenshotDir: string = '.hauntview/screenshots') {
|
|
25
|
+
this.screenshotDir = screenshotDir;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Initialize screenshot directory
|
|
30
|
+
*/
|
|
31
|
+
async initialize(): Promise<void> {
|
|
32
|
+
try {
|
|
33
|
+
await fs.mkdir(this.screenshotDir, { recursive: true });
|
|
34
|
+
} catch (error) {
|
|
35
|
+
throw new Error(`Failed to initialize screenshot directory: ${error}`);
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/**
|
|
40
|
+
* Capture screenshot from page
|
|
41
|
+
*/
|
|
42
|
+
async captureScreenshot(
|
|
43
|
+
page: Page,
|
|
44
|
+
profileId: string,
|
|
45
|
+
url: string,
|
|
46
|
+
viewport: Viewport,
|
|
47
|
+
options?: { fullPage?: boolean }
|
|
48
|
+
): Promise<ScreenshotMetadata> {
|
|
49
|
+
try {
|
|
50
|
+
const buffer = await page.screenshot({
|
|
51
|
+
fullPage: options?.fullPage ?? true,
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
const metadata = this.generateMetadata(profileId, url, viewport, buffer);
|
|
55
|
+
await this.storeScreenshot(metadata, buffer);
|
|
56
|
+
|
|
57
|
+
return metadata;
|
|
58
|
+
} catch (error) {
|
|
59
|
+
throw new Error(`Failed to capture screenshot: ${error}`);
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* Store screenshot on disk
|
|
65
|
+
*/
|
|
66
|
+
async storeScreenshot(metadata: ScreenshotMetadata, buffer: Buffer): Promise<void> {
|
|
67
|
+
const filePath = path.join(this.screenshotDir, metadata.fileName);
|
|
68
|
+
|
|
69
|
+
try {
|
|
70
|
+
// Ensure subdirectory exists
|
|
71
|
+
await fs.mkdir(path.dirname(filePath), { recursive: true });
|
|
72
|
+
|
|
73
|
+
// Write screenshot
|
|
74
|
+
await fs.writeFile(filePath, buffer);
|
|
75
|
+
|
|
76
|
+
// Store in memory index
|
|
77
|
+
this.screenshots.set(metadata.fileName, {
|
|
78
|
+
metadata,
|
|
79
|
+
buffer,
|
|
80
|
+
hash: metadata.hash,
|
|
81
|
+
});
|
|
82
|
+
|
|
83
|
+
// Update hash index for deduplication
|
|
84
|
+
if (!this.hashIndex.has(metadata.hash)) {
|
|
85
|
+
this.hashIndex.set(metadata.hash, []);
|
|
86
|
+
}
|
|
87
|
+
this.hashIndex.get(metadata.hash)!.push(metadata.fileName);
|
|
88
|
+
} catch (error) {
|
|
89
|
+
throw new Error(`Failed to store screenshot: ${error}`);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* Retrieve screenshot by filename
|
|
95
|
+
*/
|
|
96
|
+
async getScreenshot(fileName: string): Promise<ScreenshotMetadata | null> {
|
|
97
|
+
const stored = this.screenshots.get(fileName);
|
|
98
|
+
if (stored) {
|
|
99
|
+
return stored.metadata;
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
// Try to load from disk
|
|
103
|
+
const filePath = path.join(this.screenshotDir, fileName);
|
|
104
|
+
try {
|
|
105
|
+
const buffer = await fs.readFile(filePath);
|
|
106
|
+
const hash = this.hashBuffer(buffer);
|
|
107
|
+
|
|
108
|
+
const metadata: ScreenshotMetadata = {
|
|
109
|
+
profileId: fileName.split('/')[0],
|
|
110
|
+
timestamp: parseInt(fileName.match(/\d+/)?.[0] || String(Date.now())),
|
|
111
|
+
url: '',
|
|
112
|
+
viewport: { width: 1280, height: 720, isMobile: false, hasTouch: false },
|
|
113
|
+
fileName,
|
|
114
|
+
hash,
|
|
115
|
+
};
|
|
116
|
+
|
|
117
|
+
this.screenshots.set(fileName, {
|
|
118
|
+
metadata,
|
|
119
|
+
buffer,
|
|
120
|
+
hash,
|
|
121
|
+
});
|
|
122
|
+
|
|
123
|
+
return metadata;
|
|
124
|
+
} catch {
|
|
125
|
+
return null;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Find duplicate screenshots by hash
|
|
131
|
+
*/
|
|
132
|
+
async findDuplicates(fileName: string): Promise<string[]> {
|
|
133
|
+
const screenshot = this.screenshots.get(fileName);
|
|
134
|
+
if (!screenshot) {
|
|
135
|
+
return [];
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
const duplicates = this.hashIndex.get(screenshot.hash) || [];
|
|
139
|
+
return duplicates.filter((f) => f !== fileName);
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Compare two screenshots using pixelmatch and pngjs
|
|
144
|
+
*/
|
|
145
|
+
async compareScreenshots(
|
|
146
|
+
fileName1: string,
|
|
147
|
+
fileName2: string
|
|
148
|
+
): Promise<{ pixelDifference: number; percentageDifference: number; diffBuffer?: Buffer }> {
|
|
149
|
+
const screenshot1 =
|
|
150
|
+
this.screenshots.get(fileName1) || (await this.loadStoredScreenshot(fileName1));
|
|
151
|
+
const screenshot2 =
|
|
152
|
+
this.screenshots.get(fileName2) || (await this.loadStoredScreenshot(fileName2));
|
|
153
|
+
|
|
154
|
+
if (!screenshot1 || !screenshot2) {
|
|
155
|
+
throw new Error('One or both screenshots not found');
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
// Simple comparison: if hashes match, identical
|
|
159
|
+
if (screenshot1.hash === screenshot2.hash) {
|
|
160
|
+
return { pixelDifference: 0, percentageDifference: 0 };
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
try {
|
|
164
|
+
const img1 = PNG.sync.read(screenshot1.buffer);
|
|
165
|
+
const img2 = PNG.sync.read(screenshot2.buffer);
|
|
166
|
+
|
|
167
|
+
const width = Math.max(img1.width, img2.width);
|
|
168
|
+
const height = Math.max(img1.height, img2.height);
|
|
169
|
+
|
|
170
|
+
// Normalize dimensions if they differ
|
|
171
|
+
const canvas1 = new PNG({ width, height });
|
|
172
|
+
const canvas2 = new PNG({ width, height });
|
|
173
|
+
PNG.bitblt(img1, canvas1, 0, 0, img1.width, img1.height, 0, 0);
|
|
174
|
+
PNG.bitblt(img2, canvas2, 0, 0, img2.width, img2.height, 0, 0);
|
|
175
|
+
|
|
176
|
+
const pixelmatchModule = await import('pixelmatch');
|
|
177
|
+
const pixelmatch = pixelmatchModule.default || pixelmatchModule;
|
|
178
|
+
|
|
179
|
+
const diff = new PNG({ width, height });
|
|
180
|
+
const pixelDifference = pixelmatch(canvas1.data, canvas2.data, diff.data, width, height, {
|
|
181
|
+
threshold: 0.1,
|
|
182
|
+
});
|
|
183
|
+
|
|
184
|
+
const totalPixels = width * height;
|
|
185
|
+
const percentageDifference = totalPixels > 0 ? pixelDifference / totalPixels : 0;
|
|
186
|
+
const diffBuffer = PNG.sync.write(diff);
|
|
187
|
+
|
|
188
|
+
return {
|
|
189
|
+
pixelDifference,
|
|
190
|
+
percentageDifference,
|
|
191
|
+
diffBuffer,
|
|
192
|
+
};
|
|
193
|
+
} catch {
|
|
194
|
+
// Fallback for non-PNG or decoding issue
|
|
195
|
+
return { pixelDifference: -1, percentageDifference: 1 };
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
|
|
199
|
+
private async loadStoredScreenshot(fileName: string): Promise<StoredScreenshot | null> {
|
|
200
|
+
const filePath = path.join(this.screenshotDir, fileName);
|
|
201
|
+
try {
|
|
202
|
+
const buffer = await fs.readFile(filePath);
|
|
203
|
+
const hash = this.hashBuffer(buffer);
|
|
204
|
+
const metadata: ScreenshotMetadata = {
|
|
205
|
+
profileId: fileName.split('/')[0] || 'default',
|
|
206
|
+
timestamp: Date.now(),
|
|
207
|
+
url: '',
|
|
208
|
+
viewport: { width: 1280, height: 720, isMobile: false, hasTouch: false },
|
|
209
|
+
fileName,
|
|
210
|
+
hash,
|
|
211
|
+
};
|
|
212
|
+
const stored = { metadata, buffer, hash };
|
|
213
|
+
this.screenshots.set(fileName, stored);
|
|
214
|
+
return stored;
|
|
215
|
+
} catch {
|
|
216
|
+
return null;
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
/**
|
|
221
|
+
* Clean up screenshots older than specified time
|
|
222
|
+
*/
|
|
223
|
+
async cleanup(maxAgeMs: number = 7 * 24 * 60 * 60 * 1000): Promise<number> {
|
|
224
|
+
let removedCount = 0;
|
|
225
|
+
const now = Date.now();
|
|
226
|
+
|
|
227
|
+
try {
|
|
228
|
+
const files = await fs.readdir(this.screenshotDir, { recursive: true });
|
|
229
|
+
|
|
230
|
+
for (const file of files) {
|
|
231
|
+
const filePath = path.join(this.screenshotDir, String(file));
|
|
232
|
+
const stat = await fs.stat(filePath);
|
|
233
|
+
|
|
234
|
+
if (now - stat.mtimeMs > maxAgeMs) {
|
|
235
|
+
await fs.unlink(filePath);
|
|
236
|
+
this.screenshots.delete(String(file));
|
|
237
|
+
removedCount++;
|
|
238
|
+
}
|
|
239
|
+
}
|
|
240
|
+
} catch (error) {
|
|
241
|
+
throw new Error(`Failed to cleanup screenshots: ${error}`);
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
return removedCount;
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/**
|
|
248
|
+
* Get all screenshots for a profile
|
|
249
|
+
*/
|
|
250
|
+
async getProfileScreenshots(profileId: string): Promise<ScreenshotMetadata[]> {
|
|
251
|
+
const screenshots: ScreenshotMetadata[] = [];
|
|
252
|
+
|
|
253
|
+
for (const stored of this.screenshots.values()) {
|
|
254
|
+
if (stored.metadata.profileId === profileId) {
|
|
255
|
+
screenshots.push(stored.metadata);
|
|
256
|
+
}
|
|
257
|
+
}
|
|
258
|
+
|
|
259
|
+
return screenshots.sort((a, b) => a.timestamp - b.timestamp);
|
|
260
|
+
}
|
|
261
|
+
|
|
262
|
+
/**
|
|
263
|
+
* Generate metadata for screenshot
|
|
264
|
+
*/
|
|
265
|
+
private generateMetadata(
|
|
266
|
+
profileId: string,
|
|
267
|
+
url: string,
|
|
268
|
+
viewport: Viewport,
|
|
269
|
+
buffer: Buffer
|
|
270
|
+
): ScreenshotMetadata {
|
|
271
|
+
const timestamp = Date.now();
|
|
272
|
+
const hash = this.hashBuffer(buffer);
|
|
273
|
+
const fileName = `${profileId}/${timestamp}-${hash.substring(0, 8)}.png`;
|
|
274
|
+
|
|
275
|
+
return {
|
|
276
|
+
profileId,
|
|
277
|
+
timestamp,
|
|
278
|
+
url,
|
|
279
|
+
viewport,
|
|
280
|
+
fileName,
|
|
281
|
+
hash,
|
|
282
|
+
};
|
|
283
|
+
}
|
|
284
|
+
|
|
285
|
+
/**
|
|
286
|
+
* Calculate hash of buffer
|
|
287
|
+
*/
|
|
288
|
+
private hashBuffer(buffer: Buffer): string {
|
|
289
|
+
return crypto.createHash('sha256').update(buffer).digest('hex');
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
/**
|
|
293
|
+
* Get screenshot statistics
|
|
294
|
+
*/
|
|
295
|
+
getStats(): {
|
|
296
|
+
totalScreenshots: number;
|
|
297
|
+
uniqueScreenshots: number;
|
|
298
|
+
totalSize: number;
|
|
299
|
+
} {
|
|
300
|
+
let totalSize = 0;
|
|
301
|
+
|
|
302
|
+
for (const stored of this.screenshots.values()) {
|
|
303
|
+
totalSize += stored.buffer.length;
|
|
304
|
+
}
|
|
305
|
+
|
|
306
|
+
return {
|
|
307
|
+
totalScreenshots: this.screenshots.size,
|
|
308
|
+
uniqueScreenshots: this.hashIndex.size,
|
|
309
|
+
totalSize,
|
|
310
|
+
};
|
|
311
|
+
}
|
|
312
|
+
}
|
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* src/core/system-capability.ts
|
|
3
|
+
*
|
|
4
|
+
* System hardware capability detection, heuristic concurrency recommendations,
|
|
5
|
+
* validation, and runtime clamping.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
import * as os from 'os';
|
|
9
|
+
|
|
10
|
+
export interface SystemSpecs {
|
|
11
|
+
logicalCores: number;
|
|
12
|
+
cpuModel: string;
|
|
13
|
+
totalMemoryBytes: number;
|
|
14
|
+
freeMemoryBytes: number;
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
export interface ConcurrencyRecommendation {
|
|
18
|
+
cpuBound: number;
|
|
19
|
+
ramBound: number;
|
|
20
|
+
recommendedMax: number;
|
|
21
|
+
defaultSuggested: number;
|
|
22
|
+
isConstrained: boolean;
|
|
23
|
+
constraintReason?: string;
|
|
24
|
+
specs: SystemSpecs;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
export interface ConcurrencyValidationResult {
|
|
28
|
+
valid: boolean;
|
|
29
|
+
clampedValue: number;
|
|
30
|
+
warning?: string;
|
|
31
|
+
errorMessage?: string;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* Reads live machine specs using Node's os module
|
|
36
|
+
*/
|
|
37
|
+
export function getLiveSystemSpecs(): SystemSpecs {
|
|
38
|
+
let logicalCores = 1;
|
|
39
|
+
try {
|
|
40
|
+
if (typeof os.availableParallelism === 'function') {
|
|
41
|
+
logicalCores = os.availableParallelism();
|
|
42
|
+
} else {
|
|
43
|
+
logicalCores = os.cpus().length || 1;
|
|
44
|
+
}
|
|
45
|
+
} catch {
|
|
46
|
+
logicalCores = 1;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
let cpuModel = 'Generic CPU';
|
|
50
|
+
try {
|
|
51
|
+
const cpus = os.cpus();
|
|
52
|
+
if (cpus && cpus.length > 0 && cpus[0].model) {
|
|
53
|
+
cpuModel = cpus[0].model.trim();
|
|
54
|
+
}
|
|
55
|
+
} catch {
|
|
56
|
+
// Fallback to generic CPU
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
return {
|
|
60
|
+
logicalCores,
|
|
61
|
+
cpuModel,
|
|
62
|
+
totalMemoryBytes: os.totalmem(),
|
|
63
|
+
freeMemoryBytes: os.freemem(),
|
|
64
|
+
};
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Computes hardware-aware concurrency limits using conservative heuristics:
|
|
69
|
+
* - CPU bound: roughly half logical cores (min 1) to account for hyperthreading and browser overhead
|
|
70
|
+
* - RAM bound: ~2 GB per concurrent browser execution
|
|
71
|
+
* - Constrained: < 4 GB RAM or < 2 cores caps concurrency at 1
|
|
72
|
+
*/
|
|
73
|
+
export function evaluateSystemCapability(customSpecs?: SystemSpecs): ConcurrencyRecommendation {
|
|
74
|
+
const specs = customSpecs ?? getLiveSystemSpecs();
|
|
75
|
+
const totalMemoryGb = specs.totalMemoryBytes / (1024 * 1024 * 1024);
|
|
76
|
+
|
|
77
|
+
const cpuBound = Math.max(1, Math.floor(specs.logicalCores / 2));
|
|
78
|
+
const ramBound = Math.max(1, Math.floor(totalMemoryGb / 2));
|
|
79
|
+
|
|
80
|
+
const isConstrained = specs.logicalCores < 2 || totalMemoryGb < 3.5;
|
|
81
|
+
|
|
82
|
+
let recommendedMax: number;
|
|
83
|
+
let constraintReason: string | undefined;
|
|
84
|
+
|
|
85
|
+
if (isConstrained) {
|
|
86
|
+
recommendedMax = 1;
|
|
87
|
+
constraintReason = `Your system has limited hardware resources (${specs.logicalCores} cores, ${totalMemoryGb.toFixed(1)} GB RAM). Concurrency is not recommended and is capped at 1.`;
|
|
88
|
+
} else {
|
|
89
|
+
recommendedMax = Math.max(1, Math.min(cpuBound, ramBound));
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const defaultSuggested = Math.min(2, recommendedMax);
|
|
93
|
+
|
|
94
|
+
return {
|
|
95
|
+
cpuBound,
|
|
96
|
+
ramBound,
|
|
97
|
+
recommendedMax,
|
|
98
|
+
defaultSuggested,
|
|
99
|
+
isConstrained,
|
|
100
|
+
constraintReason,
|
|
101
|
+
specs,
|
|
102
|
+
};
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Validates a user-requested concurrency amount against machine recommendations.
|
|
107
|
+
* Rejects values that exceed recommendedMax with an informative explanation.
|
|
108
|
+
*/
|
|
109
|
+
export function validateConcurrencyAmount(
|
|
110
|
+
requested: number,
|
|
111
|
+
recommendation: ConcurrencyRecommendation
|
|
112
|
+
): ConcurrencyValidationResult {
|
|
113
|
+
const { recommendedMax, specs } = recommendation;
|
|
114
|
+
const totalMemoryGb = specs.totalMemoryBytes / (1024 * 1024 * 1024);
|
|
115
|
+
|
|
116
|
+
if (requested < 1) {
|
|
117
|
+
return {
|
|
118
|
+
valid: false,
|
|
119
|
+
clampedValue: 1,
|
|
120
|
+
errorMessage: 'Concurrency amount must be at least 1.',
|
|
121
|
+
};
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
if (requested > recommendedMax) {
|
|
125
|
+
const errorMessage = `Your ${specs.cpuModel} (${specs.logicalCores} cores/threads, ${totalMemoryGb.toFixed(1)} GB RAM) supports at most ${recommendedMax} concurrent rites; ${requested} would likely freeze the machine.`;
|
|
126
|
+
return {
|
|
127
|
+
valid: false,
|
|
128
|
+
clampedValue: recommendedMax,
|
|
129
|
+
errorMessage,
|
|
130
|
+
};
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
return {
|
|
134
|
+
valid: true,
|
|
135
|
+
clampedValue: requested,
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Runtime clamping for config values loaded from disk or env vars
|
|
141
|
+
*/
|
|
142
|
+
export function clampConcurrencyAmount(
|
|
143
|
+
requested: number,
|
|
144
|
+
recommendation: ConcurrencyRecommendation
|
|
145
|
+
): { effectiveAmount: number; wasClamped: boolean; warning?: string } {
|
|
146
|
+
const { recommendedMax, specs } = recommendation;
|
|
147
|
+
if (requested > recommendedMax) {
|
|
148
|
+
const totalMemoryGb = specs.totalMemoryBytes / (1024 * 1024 * 1024);
|
|
149
|
+
const warning = `[haunt] Configured concurrency amount (${requested}) exceeds machine recommended limit (${recommendedMax}) for ${specs.cpuModel} (${totalMemoryGb.toFixed(1)} GB RAM). Clamping to ${recommendedMax}.`;
|
|
150
|
+
return {
|
|
151
|
+
effectiveAmount: recommendedMax,
|
|
152
|
+
wasClamped: true,
|
|
153
|
+
warning,
|
|
154
|
+
};
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
return {
|
|
158
|
+
effectiveAmount: Math.max(1, requested),
|
|
159
|
+
wasClamped: false,
|
|
160
|
+
};
|
|
161
|
+
}
|
|
@@ -0,0 +1,230 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* visual-diff.ts — Ectoplasm diff engine
|
|
3
|
+
*
|
|
4
|
+
* Compares two PNG screenshots using pixelmatch and clusters changed pixels
|
|
5
|
+
* into bounding-box regions (the "ectoplasm overlay").
|
|
6
|
+
*
|
|
7
|
+
* changedRatio is a pure fact about pixels — it is NOT a finding by itself.
|
|
8
|
+
* Callers must attach a mechanism (overflow, failed request, etc.) before
|
|
9
|
+
* raising a Finding.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import fs from 'fs';
|
|
13
|
+
import path from 'path';
|
|
14
|
+
import { PNG } from 'pngjs';
|
|
15
|
+
import pixelmatch from 'pixelmatch';
|
|
16
|
+
|
|
17
|
+
export interface Rect {
|
|
18
|
+
x: number;
|
|
19
|
+
y: number;
|
|
20
|
+
width: number;
|
|
21
|
+
height: number;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
export interface DiffResult {
|
|
25
|
+
/** Fraction of pixels that changed, 0..1 */
|
|
26
|
+
changedRatio: number;
|
|
27
|
+
/** Absolute path where the ectoplasm PNG was written */
|
|
28
|
+
ectoplasmPath: string;
|
|
29
|
+
/** Up to 20 change regions, sorted by area descending */
|
|
30
|
+
changeRegions: Rect[];
|
|
31
|
+
/** Masked regions that were blanked before diffing */
|
|
32
|
+
maskedRegions: Rect[];
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
/** Maximum PNG height (px) before cropping */
|
|
36
|
+
const MAX_HEIGHT = 12_000;
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Compute a pixel diff between two PNGs and write an ectoplasm overlay.
|
|
40
|
+
*
|
|
41
|
+
* @param baselinePath - Path to the baseline (living page) PNG
|
|
42
|
+
* @param apparitionPath - Path to the apparition (condition run) PNG
|
|
43
|
+
* @param outputPath - Path where the ectoplasm diff PNG will be written
|
|
44
|
+
* @param maskedRegions - Optional areas to blank in both images before diffing
|
|
45
|
+
*/
|
|
46
|
+
export async function computeDiff(
|
|
47
|
+
baselinePath: string,
|
|
48
|
+
apparitionPath: string,
|
|
49
|
+
outputPath: string,
|
|
50
|
+
maskedRegions: Rect[] = []
|
|
51
|
+
): Promise<DiffResult> {
|
|
52
|
+
// Read both PNGs synchronously
|
|
53
|
+
const baselineBuffer = fs.readFileSync(baselinePath);
|
|
54
|
+
const apparitionBuffer = fs.readFileSync(apparitionPath);
|
|
55
|
+
|
|
56
|
+
const baselinePng = PNG.sync.read(baselineBuffer);
|
|
57
|
+
const apparitionPng = PNG.sync.read(apparitionBuffer);
|
|
58
|
+
|
|
59
|
+
// Normalise to the same canvas size (union of both dims), then cap height
|
|
60
|
+
const rawWidth = Math.max(baselinePng.width, apparitionPng.width);
|
|
61
|
+
const rawHeight = Math.min(Math.max(baselinePng.height, apparitionPng.height), MAX_HEIGHT);
|
|
62
|
+
|
|
63
|
+
// Create canvases of the normalised size (zero-initialised = transparent/black)
|
|
64
|
+
const canvasA = new PNG({ width: rawWidth, height: rawHeight });
|
|
65
|
+
const canvasB = new PNG({ width: rawWidth, height: rawHeight });
|
|
66
|
+
|
|
67
|
+
// Blit source images into canvases (cropping to MAX_HEIGHT implicitly)
|
|
68
|
+
const blitHeight = (src: PNG) => Math.min(src.height, rawHeight);
|
|
69
|
+
PNG.bitblt(baselinePng, canvasA, 0, 0, baselinePng.width, blitHeight(baselinePng), 0, 0);
|
|
70
|
+
PNG.bitblt(apparitionPng, canvasB, 0, 0, apparitionPng.width, blitHeight(apparitionPng), 0, 0);
|
|
71
|
+
|
|
72
|
+
// Apply masked regions: set identical pixels in both canvases so they never diff
|
|
73
|
+
for (const region of maskedRegions) {
|
|
74
|
+
applyMask(canvasA, region);
|
|
75
|
+
applyMask(canvasB, region);
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
const diffPng = new PNG({ width: rawWidth, height: rawHeight });
|
|
79
|
+
|
|
80
|
+
const changedPixels = pixelmatch(canvasA.data, canvasB.data, diffPng.data, rawWidth, rawHeight, {
|
|
81
|
+
threshold: 0.1,
|
|
82
|
+
includeAA: false,
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
const totalPixels = rawWidth * rawHeight;
|
|
86
|
+
const changedRatio = totalPixels > 0 ? changedPixels / totalPixels : 0;
|
|
87
|
+
|
|
88
|
+
// Write ectoplasm PNG, creating parent directory as needed
|
|
89
|
+
const outputDir = path.dirname(outputPath);
|
|
90
|
+
fs.mkdirSync(outputDir, { recursive: true });
|
|
91
|
+
const diffBuffer = PNG.sync.write(diffPng);
|
|
92
|
+
fs.writeFileSync(outputPath, diffBuffer);
|
|
93
|
+
|
|
94
|
+
// Build a boolean mask of which pixels actually changed.
|
|
95
|
+
// We compare the two source canvases directly rather than interpreting
|
|
96
|
+
// pixelmatch's coloured output (which tints even unchanged pixels gray).
|
|
97
|
+
const changedMask = buildChangedMask(canvasA, canvasB, rawWidth, rawHeight, 0.1);
|
|
98
|
+
|
|
99
|
+
// Cluster changed pixels into bounding-box regions via BFS flood fill
|
|
100
|
+
const changeRegions = clusterChangedRegions(changedMask, rawWidth, rawHeight);
|
|
101
|
+
|
|
102
|
+
return {
|
|
103
|
+
changedRatio,
|
|
104
|
+
ectoplasmPath: outputPath,
|
|
105
|
+
changeRegions,
|
|
106
|
+
maskedRegions,
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
// ---------------------------------------------------------------------------
|
|
111
|
+
// Helpers
|
|
112
|
+
// ---------------------------------------------------------------------------
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* Zero out a rectangular region in a PNG (RGBA → 0,0,0,0) so it produces
|
|
116
|
+
* no diff signal against the other canvas which receives the same treatment.
|
|
117
|
+
*/
|
|
118
|
+
function applyMask(png: PNG, region: Rect): void {
|
|
119
|
+
const x2 = Math.min(region.x + region.width, png.width);
|
|
120
|
+
const y2 = Math.min(region.y + region.height, png.height);
|
|
121
|
+
|
|
122
|
+
for (let y = Math.max(0, region.y); y < y2; y++) {
|
|
123
|
+
for (let x = Math.max(0, region.x); x < x2; x++) {
|
|
124
|
+
const idx = (y * png.width + x) * 4;
|
|
125
|
+
png.data[idx] = 0;
|
|
126
|
+
png.data[idx + 1] = 0;
|
|
127
|
+
png.data[idx + 2] = 0;
|
|
128
|
+
png.data[idx + 3] = 0;
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
|
|
133
|
+
/**
|
|
134
|
+
* Build a boolean mask (Uint8Array, 1 = changed) by directly comparing the
|
|
135
|
+
* two source canvases. This avoids interpreting pixelmatch's coloured diff
|
|
136
|
+
* output, which tints even unchanged pixels with a faint gray so they are
|
|
137
|
+
* visible against a white background — those tinted pixels are NOT real diffs.
|
|
138
|
+
*
|
|
139
|
+
* A pixel is considered changed when the per-channel delta for any channel
|
|
140
|
+
* exceeds the pixelmatch threshold (0..255 scale) or alpha differs.
|
|
141
|
+
*/
|
|
142
|
+
function buildChangedMask(
|
|
143
|
+
canvasA: PNG,
|
|
144
|
+
canvasB: PNG,
|
|
145
|
+
width: number,
|
|
146
|
+
height: number,
|
|
147
|
+
threshold: number // 0..1 as used by pixelmatch
|
|
148
|
+
): Uint8Array {
|
|
149
|
+
const mask = new Uint8Array(width * height);
|
|
150
|
+
const thresholdByte = threshold * 255;
|
|
151
|
+
|
|
152
|
+
for (let i = 0; i < width * height; i++) {
|
|
153
|
+
const p = i * 4;
|
|
154
|
+
const dr = Math.abs(canvasA.data[p] - canvasB.data[p]);
|
|
155
|
+
const dg = Math.abs(canvasA.data[p + 1] - canvasB.data[p + 1]);
|
|
156
|
+
const db = Math.abs(canvasA.data[p + 2] - canvasB.data[p + 2]);
|
|
157
|
+
const da = Math.abs(canvasA.data[p + 3] - canvasB.data[p + 3]);
|
|
158
|
+
if (dr > thresholdByte || dg > thresholdByte || db > thresholdByte || da > thresholdByte) {
|
|
159
|
+
mask[i] = 1;
|
|
160
|
+
}
|
|
161
|
+
}
|
|
162
|
+
return mask;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
/**
|
|
166
|
+
* Cluster changed pixels (mask[i] === 1) into bounding-box regions via BFS
|
|
167
|
+
* flood fill. Returns up to 20 regions, sorted by area descending.
|
|
168
|
+
*/
|
|
169
|
+
function clusterChangedRegions(changedMask: Uint8Array, width: number, height: number): Rect[] {
|
|
170
|
+
const visited = new Uint8Array(width * height);
|
|
171
|
+
const regions: Rect[] = [];
|
|
172
|
+
|
|
173
|
+
for (let startY = 0; startY < height; startY++) {
|
|
174
|
+
for (let startX = 0; startX < width; startX++) {
|
|
175
|
+
const idx = startY * width + startX;
|
|
176
|
+
if (visited[idx] || !changedMask[idx]) {
|
|
177
|
+
visited[idx] = 1;
|
|
178
|
+
continue;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
// BFS over the connected component
|
|
182
|
+
const queue: number[] = [idx];
|
|
183
|
+
visited[idx] = 1;
|
|
184
|
+
|
|
185
|
+
let minX = startX;
|
|
186
|
+
let maxX = startX;
|
|
187
|
+
let minY = startY;
|
|
188
|
+
let maxY = startY;
|
|
189
|
+
|
|
190
|
+
let head = 0;
|
|
191
|
+
while (head < queue.length) {
|
|
192
|
+
const cur = queue[head++];
|
|
193
|
+
const cy = Math.floor(cur / width);
|
|
194
|
+
const cx = cur % width;
|
|
195
|
+
|
|
196
|
+
if (cx < minX) minX = cx;
|
|
197
|
+
if (cx > maxX) maxX = cx;
|
|
198
|
+
if (cy < minY) minY = cy;
|
|
199
|
+
if (cy > maxY) maxY = cy;
|
|
200
|
+
|
|
201
|
+
// 4-connected neighbours
|
|
202
|
+
const neighbours = [
|
|
203
|
+
cy > 0 ? cur - width : -1,
|
|
204
|
+
cy < height - 1 ? cur + width : -1,
|
|
205
|
+
cx > 0 ? cur - 1 : -1,
|
|
206
|
+
cx < width - 1 ? cur + 1 : -1,
|
|
207
|
+
];
|
|
208
|
+
|
|
209
|
+
for (const nb of neighbours) {
|
|
210
|
+
if (nb < 0 || visited[nb]) continue;
|
|
211
|
+
if (changedMask[nb]) {
|
|
212
|
+
visited[nb] = 1;
|
|
213
|
+
queue.push(nb);
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
regions.push({
|
|
219
|
+
x: minX,
|
|
220
|
+
y: minY,
|
|
221
|
+
width: maxX - minX + 1,
|
|
222
|
+
height: maxY - minY + 1,
|
|
223
|
+
});
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
// Sort by area descending, keep at most 20
|
|
228
|
+
regions.sort((a, b) => b.width * b.height - a.width * a.height);
|
|
229
|
+
return regions.slice(0, 20);
|
|
230
|
+
}
|