@cappa/core 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.
- package/dist/index.cjs +885 -6
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +365 -3
- package/dist/index.d.mts +365 -3
- package/dist/index.mjs +860 -7
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/dist/index.cjs
CHANGED
|
@@ -844,6 +844,17 @@ var ScreenshotFileSystem = class {
|
|
|
844
844
|
await node_fs_promises.default.writeFile(filepath, data);
|
|
845
845
|
}
|
|
846
846
|
/**
|
|
847
|
+
* Remove a screenshot's diff image and metadata sidecar, if any.
|
|
848
|
+
*
|
|
849
|
+
* A run that does not clear `diff/` — a filtered or single-screenshot
|
|
850
|
+
* re-capture — would otherwise leave the previous run's diff behind for a
|
|
851
|
+
* screenshot that now passes, and a screenshot with a diff is `changed`.
|
|
852
|
+
*/
|
|
853
|
+
async removeDiffFiles(filename) {
|
|
854
|
+
const filepath = this.getDiffFilePath(filename);
|
|
855
|
+
await Promise.all([node_fs_promises.default.rm(filepath, { force: true }), node_fs_promises.default.rm(toDiffMetaPath(filepath), { force: true })]);
|
|
856
|
+
}
|
|
857
|
+
/**
|
|
847
858
|
* Get the path to a diff metadata sidecar file (`<name>.json`)
|
|
848
859
|
*/
|
|
849
860
|
getDiffMetaFilePath(filename) {
|
|
@@ -1857,6 +1868,7 @@ var ScreenshotTool = class {
|
|
|
1857
1868
|
const saveDiff = extras.saveDiffImage ?? false;
|
|
1858
1869
|
const diffFilename = extras.diffImageFilename ?? filename;
|
|
1859
1870
|
const diffOverride = extras.diff;
|
|
1871
|
+
await this.filesystem.removeDiffFiles(diffFilename);
|
|
1860
1872
|
if (!await this.filesystem.hasExpectedFile(filename)) {
|
|
1861
1873
|
this.logger.debug(`Expected image not found for ${filename}, taking screenshot`);
|
|
1862
1874
|
result.filepath = await this.takeScreenshot(page, filename, options);
|
|
@@ -2056,6 +2068,204 @@ var ScreenshotTool = class {
|
|
|
2056
2068
|
}
|
|
2057
2069
|
};
|
|
2058
2070
|
//#endregion
|
|
2071
|
+
//#region src/agent/paths.ts
|
|
2072
|
+
/**
|
|
2073
|
+
* Where agent review keeps its state, inside `outputDir`.
|
|
2074
|
+
*
|
|
2075
|
+
* Its own module so screenshot collection can read the report without
|
|
2076
|
+
* importing the review pipeline, which itself collects screenshots.
|
|
2077
|
+
*/
|
|
2078
|
+
const AGENT_DIRNAME = ".cappa-agent";
|
|
2079
|
+
/** Bumped only if `request.json` or `report.json` change incompatibly. */
|
|
2080
|
+
const AGENT_REPORT_VERSION = 1;
|
|
2081
|
+
const agentDir = (outputDir) => node_path.default.resolve(outputDir, AGENT_DIRNAME);
|
|
2082
|
+
const judgmentsRoot = (outputDir) => node_path.default.join(agentDir(outputDir), "judgments");
|
|
2083
|
+
const agentReportPath = (outputDir) => node_path.default.join(agentDir(outputDir), "report.json");
|
|
2084
|
+
//#endregion
|
|
2085
|
+
//#region src/agent/verdict.ts
|
|
2086
|
+
/**
|
|
2087
|
+
* What a reviewer — heuristic or agent — believes a changed screenshot is.
|
|
2088
|
+
*
|
|
2089
|
+
* `ambiguous` is only ever produced by the heuristic: it is the signal that
|
|
2090
|
+
* the change has to be looked at, and an agent's verdict must resolve it into
|
|
2091
|
+
* one of the other three.
|
|
2092
|
+
*/
|
|
2093
|
+
const VERDICT_LABELS = [
|
|
2094
|
+
"regression-likely",
|
|
2095
|
+
"intentional-likely",
|
|
2096
|
+
"noise-likely",
|
|
2097
|
+
"ambiguous"
|
|
2098
|
+
];
|
|
2099
|
+
/** The labels a judge may hand back — everything but `ambiguous`. */
|
|
2100
|
+
const JUDGED_LABELS = [
|
|
2101
|
+
"regression-likely",
|
|
2102
|
+
"intentional-likely",
|
|
2103
|
+
"noise-likely"
|
|
2104
|
+
];
|
|
2105
|
+
const ACTION_BY_LABEL = {
|
|
2106
|
+
"regression-likely": "investigate",
|
|
2107
|
+
"intentional-likely": "approve-if-intended",
|
|
2108
|
+
"noise-likely": "mask-or-approve",
|
|
2109
|
+
ambiguous: "investigate"
|
|
2110
|
+
};
|
|
2111
|
+
const isVerdictLabel = (value) => typeof value === "string" && VERDICT_LABELS.includes(value);
|
|
2112
|
+
const isJudgedLabel = (value) => typeof value === "string" && JUDGED_LABELS.includes(value);
|
|
2113
|
+
/**
|
|
2114
|
+
* Change types are normalised to kebab-case before they are compared.
|
|
2115
|
+
*
|
|
2116
|
+
* `@blazediff/interpret-native` reports `color-change` today but earlier
|
|
2117
|
+
* releases reported `ColorChange`; normalising keeps the heuristic working
|
|
2118
|
+
* across a diff-engine upgrade instead of silently degrading every screenshot
|
|
2119
|
+
* to `ambiguous`.
|
|
2120
|
+
*/
|
|
2121
|
+
const normalizeChangeType = (changeType) => changeType.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
|
|
2122
|
+
const normalizeSeverity = (severity) => (severity ?? "").toLowerCase();
|
|
2123
|
+
/** Structural: something appeared, vanished or was replaced. */
|
|
2124
|
+
const REGRESSIVE_TYPES = /* @__PURE__ */ new Set([
|
|
2125
|
+
"content-change",
|
|
2126
|
+
"addition",
|
|
2127
|
+
"deletion"
|
|
2128
|
+
]);
|
|
2129
|
+
/** Restyled or moved, with structure intact. */
|
|
2130
|
+
const RESTYLE_TYPES = /* @__PURE__ */ new Set(["color-change", "shift"]);
|
|
2131
|
+
const NOISE_TYPES = /* @__PURE__ */ new Set(["rendering-noise"]);
|
|
2132
|
+
const ELEVATED_SEVERITY = /* @__PURE__ */ new Set(["medium", "high"]);
|
|
2133
|
+
/** Below this share of the image, a low-severity change is not perceptible. */
|
|
2134
|
+
const SUB_PERCEPTUAL_PERCENT = .01;
|
|
2135
|
+
/** Mean region confidence above which a pure recolour is trusted. */
|
|
2136
|
+
const RECOLOR_CONFIDENCE = .7;
|
|
2137
|
+
const formatPercent = (percent) => {
|
|
2138
|
+
if (percent === void 0) return "?%";
|
|
2139
|
+
return percent >= .01 ? `${percent.toFixed(2)}%` : `${percent.toFixed(3)}%`;
|
|
2140
|
+
};
|
|
2141
|
+
const countByType = (regions) => {
|
|
2142
|
+
const counts = /* @__PURE__ */ new Map();
|
|
2143
|
+
for (const region of regions) {
|
|
2144
|
+
const type = normalizeChangeType(region.changeType);
|
|
2145
|
+
counts.set(type, (counts.get(type) ?? 0) + 1);
|
|
2146
|
+
}
|
|
2147
|
+
return counts;
|
|
2148
|
+
};
|
|
2149
|
+
const formatBreakdown = (counts) => [...counts].sort((a, b) => b[1] - a[1]).map(([type, count]) => `${count} ${type}`).join(", ");
|
|
2150
|
+
const largestRegion = (regions) => regions.reduce((best, region) => !best || region.pixelCount > best.pixelCount ? region : best, void 0);
|
|
2151
|
+
const meanConfidence = (regions) => regions.length === 0 ? 0 : regions.reduce((sum, region) => sum + (region.confidence ?? 0), 0) / regions.length;
|
|
2152
|
+
/**
|
|
2153
|
+
* A one-line description of a change, shaped so that the same kind of change
|
|
2154
|
+
* on different screenshots produces the same headline — which is what lets an
|
|
2155
|
+
* agent spot one shared cause (a footer timestamp, a theme toggle) across
|
|
2156
|
+
* dozens of screenshots without opening any of them.
|
|
2157
|
+
*/
|
|
2158
|
+
const buildHeadline = (input) => {
|
|
2159
|
+
if (input.differentSizes) return "image dimensions changed";
|
|
2160
|
+
const interpretation = input.interpretation;
|
|
2161
|
+
const percent = input.percentDifference ?? interpretation?.diffPercentage;
|
|
2162
|
+
if (!interpretation || interpretation.regions.length === 0) return `${(input.numDiffPixels ?? interpretation?.diffCount)?.toLocaleString("en-US") ?? "?"} px (${formatPercent(percent)}) - no region analysis`;
|
|
2163
|
+
const regions = interpretation.regions;
|
|
2164
|
+
const counts = countByType(regions);
|
|
2165
|
+
const position = largestRegion(regions)?.position;
|
|
2166
|
+
const at = position ? ` @ ${position}` : "";
|
|
2167
|
+
const severity = normalizeSeverity(interpretation.severity) || "?";
|
|
2168
|
+
if (regions.length === 1) return `1 ${[...counts.keys()][0]}${at} (${formatPercent(percent)}, ${severity})`;
|
|
2169
|
+
return `${regions.length} regions: ${formatBreakdown(counts)}${at} (${formatPercent(percent)}, ${severity})`;
|
|
2170
|
+
};
|
|
2171
|
+
const verdict = (label, headline, rationale) => ({
|
|
2172
|
+
label,
|
|
2173
|
+
headline,
|
|
2174
|
+
rationale,
|
|
2175
|
+
action: ACTION_BY_LABEL[label]
|
|
2176
|
+
});
|
|
2177
|
+
/**
|
|
2178
|
+
* Classify a changed screenshot from its diff interpretation alone.
|
|
2179
|
+
*
|
|
2180
|
+
* Deliberately conservative: only the cases the signals settle are labelled,
|
|
2181
|
+
* and everything else is `ambiguous` so that it reaches a judge who can look
|
|
2182
|
+
* at the pixels. A wrong `noise-likely` hides a regression; a wrong
|
|
2183
|
+
* `ambiguous` costs one look.
|
|
2184
|
+
*/
|
|
2185
|
+
const deriveVerdict = (input) => {
|
|
2186
|
+
const headline = buildHeadline(input);
|
|
2187
|
+
if (input.differentSizes) return verdict("ambiguous", headline, ["expected and actual have different dimensions — content likely grew or shrank", "could be an intended content change or a broken layout"]);
|
|
2188
|
+
const interpretation = input.interpretation;
|
|
2189
|
+
if (!interpretation || interpretation.regions.length === 0) return verdict("ambiguous", headline, ["pixels differ but no change regions were found"]);
|
|
2190
|
+
const regions = interpretation.regions;
|
|
2191
|
+
const types = regions.map((region) => normalizeChangeType(region.changeType));
|
|
2192
|
+
const severity = normalizeSeverity(interpretation.severity);
|
|
2193
|
+
const percent = input.percentDifference ?? interpretation.diffPercentage;
|
|
2194
|
+
const counts = countByType(regions);
|
|
2195
|
+
if (types.every((type) => NOISE_TYPES.has(type))) return verdict("noise-likely", headline, ["every region is classified as rendering noise"]);
|
|
2196
|
+
if (percent < .01 && severity === "low") return verdict("noise-likely", headline, [`less than ${SUB_PERCEPTUAL_PERCENT}% of the image differs (${formatPercent(percent)}) at low severity`, "sub-perceptual change"]);
|
|
2197
|
+
if (types.some((type) => REGRESSIVE_TYPES.has(type)) && ELEVATED_SEVERITY.has(severity)) {
|
|
2198
|
+
const structural = [...counts].filter(([type]) => REGRESSIVE_TYPES.has(type)).map(([type, count]) => `${count} ${type}`).join(", ");
|
|
2199
|
+
return verdict("regression-likely", headline, [`${severity} severity with structural changes (${structural})`, "content or layout changed, not just styling"]);
|
|
2200
|
+
}
|
|
2201
|
+
const allRecolor = types.every((type) => type === "color-change");
|
|
2202
|
+
if (allRecolor && meanConfidence(regions) > RECOLOR_CONFIDENCE) return verdict("intentional-likely", headline, [`${regions.length} confident color-change ${regions.length === 1 ? "region" : "regions"}`, "edge structure preserved — looks like a theming or palette change"]);
|
|
2203
|
+
if (!allRecolor && types.every((type) => RESTYLE_TYPES.has(type))) return verdict("intentional-likely", headline, ["every region is a shift or color change — content moved or was restyled, structure preserved"]);
|
|
2204
|
+
return verdict("ambiguous", headline, [`mix of change types (${formatBreakdown(counts)}) at ${severity || "unknown"} severity`, `${formatPercent(percent)} of the image differs`]);
|
|
2205
|
+
};
|
|
2206
|
+
//#endregion
|
|
2207
|
+
//#region src/agent/reviewIndex.ts
|
|
2208
|
+
/**
|
|
2209
|
+
* Read the review index, or nothing.
|
|
2210
|
+
*
|
|
2211
|
+
* Never throws: like the capture manifest, the report is an extra, and a
|
|
2212
|
+
* missing or hand-edited file must not break the screenshot listing.
|
|
2213
|
+
*/
|
|
2214
|
+
const readAgentReviewIndex = async (outputDir) => {
|
|
2215
|
+
let raw;
|
|
2216
|
+
try {
|
|
2217
|
+
raw = JSON.parse(await node_fs_promises.default.readFile(agentReportPath(outputDir), "utf8"));
|
|
2218
|
+
} catch {
|
|
2219
|
+
return;
|
|
2220
|
+
}
|
|
2221
|
+
const createdAt = typeof raw?.createdAt === "string" ? Date.parse(raw.createdAt) : NaN;
|
|
2222
|
+
if (raw?.version !== 1 || Number.isNaN(createdAt) || !Array.isArray(raw.entries)) return;
|
|
2223
|
+
const reviews = /* @__PURE__ */ new Map();
|
|
2224
|
+
for (const entry of raw.entries) {
|
|
2225
|
+
if (typeof entry !== "object" || entry === null) continue;
|
|
2226
|
+
const { name, category, verdict, pending } = entry;
|
|
2227
|
+
if (typeof name !== "string" || category !== "changed") continue;
|
|
2228
|
+
if (typeof verdict !== "object" || verdict === null) continue;
|
|
2229
|
+
const v = verdict;
|
|
2230
|
+
if (!isVerdictLabel(v.label) || typeof v.headline !== "string") continue;
|
|
2231
|
+
reviews.set(name, {
|
|
2232
|
+
label: v.label,
|
|
2233
|
+
headline: v.headline,
|
|
2234
|
+
rationale: Array.isArray(v.rationale) ? v.rationale.filter((line) => typeof line === "string") : [],
|
|
2235
|
+
action: v.action,
|
|
2236
|
+
source: v.source === "agent" ? "agent" : "heuristic",
|
|
2237
|
+
...typeof v.confidence === "number" ? { confidence: v.confidence } : {},
|
|
2238
|
+
pending: pending === true,
|
|
2239
|
+
reviewedAt: new Date(createdAt).toISOString()
|
|
2240
|
+
});
|
|
2241
|
+
}
|
|
2242
|
+
return {
|
|
2243
|
+
createdAt,
|
|
2244
|
+
reviews
|
|
2245
|
+
};
|
|
2246
|
+
};
|
|
2247
|
+
const modifiedAt = async (file) => {
|
|
2248
|
+
try {
|
|
2249
|
+
return (await node_fs_promises.default.stat(file)).mtimeMs;
|
|
2250
|
+
} catch {
|
|
2251
|
+
return Number.POSITIVE_INFINITY;
|
|
2252
|
+
}
|
|
2253
|
+
};
|
|
2254
|
+
/**
|
|
2255
|
+
* The review for a changed screenshot, if it is still about these images.
|
|
2256
|
+
*
|
|
2257
|
+
* A capture after the check rewrites `actual/`, an approval rewrites
|
|
2258
|
+
* `expected/`; either makes the verdict describe pixels that are gone. File
|
|
2259
|
+
* times are compared rather than content hashed because this runs on every
|
|
2260
|
+
* listing the review UI makes.
|
|
2261
|
+
*/
|
|
2262
|
+
const freshAgentReview = async (index, outputDir, screenshot) => {
|
|
2263
|
+
const review = index?.reviews.get(screenshot.name);
|
|
2264
|
+
if (!index || !review) return void 0;
|
|
2265
|
+
const [actual, expected] = await Promise.all([modifiedAt(node_path.default.resolve(outputDir, screenshot.actualPath)), modifiedAt(node_path.default.resolve(outputDir, screenshot.expectedPath))]);
|
|
2266
|
+
return actual <= index.createdAt && expected <= index.createdAt ? review : void 0;
|
|
2267
|
+
};
|
|
2268
|
+
//#endregion
|
|
2059
2269
|
//#region src/screenshots/groupScreenshots.ts
|
|
2060
2270
|
const groupScreenshots = async (actualScreenshots, expectedScreenshots, diffScreenshots, outputDir) => {
|
|
2061
2271
|
const screenshotRepresentations = [];
|
|
@@ -2125,23 +2335,33 @@ const listPngs = async (dir) => Array.fromAsync(await (0, node_fs_promises.glob)
|
|
|
2125
2335
|
*
|
|
2126
2336
|
* The capture manifest is folded in here so every consumer — the CLI, the
|
|
2127
2337
|
* server, the review UI — sees the same `taskId`, and so a screenshot captured
|
|
2128
|
-
* before manifests existed simply has none rather than a wrong one.
|
|
2338
|
+
* before manifests existed simply has none rather than a wrong one. The last
|
|
2339
|
+
* `cappa agent check` verdict is folded in the same way, as `review`, while it
|
|
2340
|
+
* still describes the images on disk.
|
|
2129
2341
|
*/
|
|
2130
2342
|
const collectScreenshots = async (outputDir) => {
|
|
2131
|
-
const [actualScreenshots, expectedScreenshots, diffScreenshots, manifest] = await Promise.all([
|
|
2343
|
+
const [actualScreenshots, expectedScreenshots, diffScreenshots, manifest, reviewIndex] = await Promise.all([
|
|
2132
2344
|
listPngs(node_path.default.resolve(outputDir, "actual")),
|
|
2133
2345
|
listPngs(node_path.default.resolve(outputDir, "expected")),
|
|
2134
2346
|
listPngs(node_path.default.resolve(outputDir, "diff")),
|
|
2135
|
-
readCaptureManifest(outputDir)
|
|
2347
|
+
readCaptureManifest(outputDir),
|
|
2348
|
+
readAgentReviewIndex(outputDir)
|
|
2136
2349
|
]);
|
|
2137
|
-
|
|
2350
|
+
const screenshots = await groupScreenshots(actualScreenshots, expectedScreenshots, diffScreenshots, outputDir);
|
|
2351
|
+
return Promise.all(screenshots.map(async (screenshot) => {
|
|
2138
2352
|
const origin = manifest.screenshots[screenshot.name];
|
|
2139
|
-
|
|
2353
|
+
const withOrigin = origin ? {
|
|
2140
2354
|
...screenshot,
|
|
2141
2355
|
taskId: origin.taskId,
|
|
2142
2356
|
plugin: origin.plugin
|
|
2143
2357
|
} : screenshot;
|
|
2144
|
-
|
|
2358
|
+
if (withOrigin.category !== "changed" || !reviewIndex) return withOrigin;
|
|
2359
|
+
const review = await freshAgentReview(reviewIndex, outputDir, withOrigin);
|
|
2360
|
+
return review ? {
|
|
2361
|
+
...withOrigin,
|
|
2362
|
+
review
|
|
2363
|
+
} : withOrigin;
|
|
2364
|
+
}));
|
|
2145
2365
|
};
|
|
2146
2366
|
//#endregion
|
|
2147
2367
|
//#region src/engine/RunStore.ts
|
|
@@ -3182,6 +3402,642 @@ var FsScreenshotStore = class {
|
|
|
3182
3402
|
}
|
|
3183
3403
|
};
|
|
3184
3404
|
//#endregion
|
|
3405
|
+
//#region src/agent/tiles.ts
|
|
3406
|
+
const LOCATOR_MAX_WIDTH = 400;
|
|
3407
|
+
const LOCATOR_MAX_HEIGHT = 1200;
|
|
3408
|
+
const GUTTER = 12;
|
|
3409
|
+
const ROW_GUTTER = 16;
|
|
3410
|
+
const LABEL_HEIGHT = 18;
|
|
3411
|
+
const BACKGROUND = {
|
|
3412
|
+
r: 128,
|
|
3413
|
+
g: 128,
|
|
3414
|
+
b: 128
|
|
3415
|
+
};
|
|
3416
|
+
const escapeXml = (text) => text.replace(/[<>&"]/g, (c) => `&#${c.charCodeAt(0)};`);
|
|
3417
|
+
/** A caption strip, so a row reads as "#2 expected | #2 actual" at a glance. */
|
|
3418
|
+
const label = (text, width) => Buffer.from(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${LABEL_HEIGHT}"><rect width="100%" height="100%" fill="#222"/><text x="4" y="13" font-family="sans-serif" font-size="12" fill="#fff">${escapeXml(text)}</text></svg>`);
|
|
3419
|
+
const padAndClamp = (bbox, padding, width, height) => {
|
|
3420
|
+
const padX = typeof padding === "number" ? padding : padding.x;
|
|
3421
|
+
const padY = typeof padding === "number" ? padding : padding.y;
|
|
3422
|
+
const x = Math.max(0, Math.floor(bbox.x - padX));
|
|
3423
|
+
const y = Math.max(0, Math.floor(bbox.y - padY));
|
|
3424
|
+
const right = Math.min(width, Math.ceil(bbox.x + bbox.width + padX));
|
|
3425
|
+
const bottom = Math.min(height, Math.ceil(bbox.y + bbox.height + padY));
|
|
3426
|
+
return {
|
|
3427
|
+
x,
|
|
3428
|
+
y,
|
|
3429
|
+
width: Math.max(1, right - x),
|
|
3430
|
+
height: Math.max(1, bottom - y)
|
|
3431
|
+
};
|
|
3432
|
+
};
|
|
3433
|
+
const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
|
|
3434
|
+
/**
|
|
3435
|
+
* Context kept around a region: proportional to its size, within bounds.
|
|
3436
|
+
*
|
|
3437
|
+
* A fixed margin is too tight for small regions — a changed letter cropped
|
|
3438
|
+
* with 24px around it says nothing about whether a button label got
|
|
3439
|
+
* truncated — and wasteful for large ones.
|
|
3440
|
+
*/
|
|
3441
|
+
const contextPadding = (bbox, minimum) => ({
|
|
3442
|
+
x: clamp(bbox.width, minimum * 2, 160),
|
|
3443
|
+
y: clamp(bbox.height, minimum, 96)
|
|
3444
|
+
});
|
|
3445
|
+
/** Scale that fits `width`x`height` into the bounds without upscaling. */
|
|
3446
|
+
const fitScale = (width, height, maxWidth, maxHeight) => Math.min(1, maxWidth / width, maxHeight / height);
|
|
3447
|
+
const readSize$1 = async (file) => {
|
|
3448
|
+
const { width, height } = await (0, sharp.default)(file).metadata();
|
|
3449
|
+
if (!width || !height) throw new Error(`Unable to read image dimensions: ${file}`);
|
|
3450
|
+
return {
|
|
3451
|
+
width,
|
|
3452
|
+
height
|
|
3453
|
+
};
|
|
3454
|
+
};
|
|
3455
|
+
const renderCrop = async (file, box, scale) => {
|
|
3456
|
+
const crop = (0, sharp.default)(file).extract({
|
|
3457
|
+
left: box.x,
|
|
3458
|
+
top: box.y,
|
|
3459
|
+
width: box.width,
|
|
3460
|
+
height: box.height
|
|
3461
|
+
});
|
|
3462
|
+
if (scale < 1) crop.resize(Math.max(1, Math.round(box.width * scale)), Math.max(1, Math.round(box.height * scale)));
|
|
3463
|
+
return crop.png().toBuffer();
|
|
3464
|
+
};
|
|
3465
|
+
const renderRegions = async (options, width, height) => {
|
|
3466
|
+
const padding = options.padding ?? 24;
|
|
3467
|
+
const maxCropWidth = options.maxCropWidth ?? 640;
|
|
3468
|
+
const regions = options.regions.slice(0, options.maxRegions ?? 8);
|
|
3469
|
+
if (regions.length === 0) return void 0;
|
|
3470
|
+
const rows = await Promise.all(regions.map(async (region) => {
|
|
3471
|
+
const box = padAndClamp(region, contextPadding(region, padding), width, height);
|
|
3472
|
+
const scale = Math.min(1, maxCropWidth / box.width);
|
|
3473
|
+
const [expected, actual] = await Promise.all([renderCrop(options.expectedPath, box, scale), renderCrop(options.actualPath, box, scale)]);
|
|
3474
|
+
return {
|
|
3475
|
+
expected,
|
|
3476
|
+
actual,
|
|
3477
|
+
width: Math.max(1, Math.round(box.width * scale)),
|
|
3478
|
+
height: Math.max(1, Math.round(box.height * scale))
|
|
3479
|
+
};
|
|
3480
|
+
}));
|
|
3481
|
+
const columnWidth = (row) => Math.max(row.width, 96);
|
|
3482
|
+
const canvasWidth = Math.max(...rows.map((row) => columnWidth(row) * 2 + GUTTER));
|
|
3483
|
+
const canvasHeight = rows.reduce((sum, row) => sum + LABEL_HEIGHT + row.height, 0) + ROW_GUTTER * (rows.length - 1);
|
|
3484
|
+
const composites = [];
|
|
3485
|
+
let top = 0;
|
|
3486
|
+
rows.forEach((row, index) => {
|
|
3487
|
+
const column = columnWidth(row);
|
|
3488
|
+
const right = column + GUTTER;
|
|
3489
|
+
composites.push({
|
|
3490
|
+
input: label(`#${index + 1} expected`, column),
|
|
3491
|
+
left: 0,
|
|
3492
|
+
top
|
|
3493
|
+
}, {
|
|
3494
|
+
input: label(`#${index + 1} actual`, column),
|
|
3495
|
+
left: right,
|
|
3496
|
+
top
|
|
3497
|
+
}, {
|
|
3498
|
+
input: row.expected,
|
|
3499
|
+
left: 0,
|
|
3500
|
+
top: top + LABEL_HEIGHT
|
|
3501
|
+
}, {
|
|
3502
|
+
input: row.actual,
|
|
3503
|
+
left: right,
|
|
3504
|
+
top: top + LABEL_HEIGHT
|
|
3505
|
+
});
|
|
3506
|
+
top += LABEL_HEIGHT + row.height + ROW_GUTTER;
|
|
3507
|
+
});
|
|
3508
|
+
const file = node_path.default.join(options.outDir, "regions.png");
|
|
3509
|
+
await (0, sharp.default)({ create: {
|
|
3510
|
+
width: canvasWidth,
|
|
3511
|
+
height: canvasHeight,
|
|
3512
|
+
channels: 3,
|
|
3513
|
+
background: BACKGROUND
|
|
3514
|
+
} }).composite(composites).png().toFile(file);
|
|
3515
|
+
return {
|
|
3516
|
+
file,
|
|
3517
|
+
count: rows.length
|
|
3518
|
+
};
|
|
3519
|
+
};
|
|
3520
|
+
const renderLocator = async (options, width, height) => {
|
|
3521
|
+
const scale = fitScale(width, height, LOCATOR_MAX_WIDTH, LOCATOR_MAX_HEIGHT);
|
|
3522
|
+
const locatorWidth = Math.max(1, Math.round(width * scale));
|
|
3523
|
+
const locatorHeight = Math.max(1, Math.round(height * scale));
|
|
3524
|
+
const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${locatorWidth}" height="${locatorHeight}">${options.regions.map((region, index) => {
|
|
3525
|
+
const x = Math.round(region.x * scale);
|
|
3526
|
+
const y = Math.round(region.y * scale);
|
|
3527
|
+
return `<rect x="${x}" y="${y}" width="${Math.max(2, Math.round(region.width * scale))}" height="${Math.max(2, Math.round(region.height * scale))}" fill="none" stroke="red" stroke-width="2"/><text x="${x + 2}" y="${Math.max(12, y - 3)}" font-family="sans-serif" font-size="12" font-weight="bold" fill="red" stroke="#fff" stroke-width="3" paint-order="stroke">${index + 1}</text>`;
|
|
3528
|
+
}).join("")}</svg>`;
|
|
3529
|
+
const file = node_path.default.join(options.outDir, "locator.png");
|
|
3530
|
+
await (0, sharp.default)(options.diffPath ?? options.actualPath).resize(locatorWidth, locatorHeight, { fit: "fill" }).composite([{
|
|
3531
|
+
input: Buffer.from(svg),
|
|
3532
|
+
left: 0,
|
|
3533
|
+
top: 0
|
|
3534
|
+
}]).png().toFile(file);
|
|
3535
|
+
return file;
|
|
3536
|
+
};
|
|
3537
|
+
/**
|
|
3538
|
+
* Write `locator.png` and `regions.png` into `outDir`.
|
|
3539
|
+
*
|
|
3540
|
+
* Expected and actual must have the same dimensions — region boxes are only
|
|
3541
|
+
* meaningful when both images share a coordinate space. Use
|
|
3542
|
+
* {@link renderOverview} when they do not.
|
|
3543
|
+
*/
|
|
3544
|
+
const renderJudgmentTiles = async (options) => {
|
|
3545
|
+
const { width, height } = await readSize$1(options.actualPath);
|
|
3546
|
+
const [regions, locator] = await Promise.all([renderRegions(options, width, height), renderLocator(options, width, height)]);
|
|
3547
|
+
return {
|
|
3548
|
+
locator,
|
|
3549
|
+
regions: regions?.file,
|
|
3550
|
+
renderedRegions: regions?.count ?? 0
|
|
3551
|
+
};
|
|
3552
|
+
};
|
|
3553
|
+
/**
|
|
3554
|
+
* Write `overview.png`: expected and actual, scaled down side by side.
|
|
3555
|
+
*
|
|
3556
|
+
* For screenshots whose dimensions changed, where no region can be located,
|
|
3557
|
+
* this is what the judge looks at instead of two full-size images.
|
|
3558
|
+
*/
|
|
3559
|
+
const renderOverview = async (options) => {
|
|
3560
|
+
const [expectedSize, actualSize] = await Promise.all([readSize$1(options.expectedPath), readSize$1(options.actualPath)]);
|
|
3561
|
+
const scale = Math.min(fitScale(expectedSize.width, expectedSize.height, LOCATOR_MAX_WIDTH, LOCATOR_MAX_HEIGHT), fitScale(actualSize.width, actualSize.height, LOCATOR_MAX_WIDTH, LOCATOR_MAX_HEIGHT));
|
|
3562
|
+
const scaled = (size) => ({
|
|
3563
|
+
width: Math.max(1, Math.round(size.width * scale)),
|
|
3564
|
+
height: Math.max(1, Math.round(size.height * scale))
|
|
3565
|
+
});
|
|
3566
|
+
const expected = scaled(expectedSize);
|
|
3567
|
+
const actual = scaled(actualSize);
|
|
3568
|
+
const [expectedBuffer, actualBuffer] = await Promise.all([(0, sharp.default)(options.expectedPath).resize(expected.width, expected.height, { fit: "fill" }).png().toBuffer(), (0, sharp.default)(options.actualPath).resize(actual.width, actual.height, { fit: "fill" }).png().toBuffer()]);
|
|
3569
|
+
const file = node_path.default.join(options.outDir, "overview.png");
|
|
3570
|
+
await (0, sharp.default)({ create: {
|
|
3571
|
+
width: expected.width + GUTTER + actual.width,
|
|
3572
|
+
height: LABEL_HEIGHT + Math.max(expected.height, actual.height),
|
|
3573
|
+
channels: 3,
|
|
3574
|
+
background: BACKGROUND
|
|
3575
|
+
} }).composite([
|
|
3576
|
+
{
|
|
3577
|
+
input: label(`expected ${expectedSize.width}x${expectedSize.height}`, expected.width),
|
|
3578
|
+
left: 0,
|
|
3579
|
+
top: 0
|
|
3580
|
+
},
|
|
3581
|
+
{
|
|
3582
|
+
input: label(`actual ${actualSize.width}x${actualSize.height}`, actual.width),
|
|
3583
|
+
left: expected.width + GUTTER,
|
|
3584
|
+
top: 0
|
|
3585
|
+
},
|
|
3586
|
+
{
|
|
3587
|
+
input: expectedBuffer,
|
|
3588
|
+
left: 0,
|
|
3589
|
+
top: LABEL_HEIGHT
|
|
3590
|
+
},
|
|
3591
|
+
{
|
|
3592
|
+
input: actualBuffer,
|
|
3593
|
+
left: expected.width + GUTTER,
|
|
3594
|
+
top: LABEL_HEIGHT
|
|
3595
|
+
}
|
|
3596
|
+
]).png().toFile(file);
|
|
3597
|
+
return file;
|
|
3598
|
+
};
|
|
3599
|
+
//#endregion
|
|
3600
|
+
//#region src/agent/review.ts
|
|
3601
|
+
/**
|
|
3602
|
+
* Agent review: turn the screenshots on disk into something a coding agent
|
|
3603
|
+
* can judge cheaply, and fold its judgments back in.
|
|
3604
|
+
*
|
|
3605
|
+
* Nothing here captures. It reads `actual/`, `expected/` and `diff/` as the
|
|
3606
|
+
* last `cappa capture` left them, so it is safe to run repeatedly — a re-run
|
|
3607
|
+
* is how an agent's verdicts are applied, and a re-capture invalidates them
|
|
3608
|
+
* automatically because every judgment is tied to a fingerprint of the two
|
|
3609
|
+
* images it was made about.
|
|
3610
|
+
*
|
|
3611
|
+
* Layout, all inside `<outputDir>/.cappa-agent/` (dot-prefixed, so neither
|
|
3612
|
+
* screenshot collection nor the review server's static handler touch it):
|
|
3613
|
+
*
|
|
3614
|
+
* ```
|
|
3615
|
+
* report.json full report of the last check
|
|
3616
|
+
* judgments/<name>/request.json what to judge and where the evidence is
|
|
3617
|
+
* judgments/<name>/locator.png thumbnail with every region outlined
|
|
3618
|
+
* judgments/<name>/regions.png [expected | actual] crop per region
|
|
3619
|
+
* judgments/<name>/overview.png instead of the two above when sizes differ
|
|
3620
|
+
* judgments/<name>/verdict.json written by the judge
|
|
3621
|
+
* ```
|
|
3622
|
+
*/
|
|
3623
|
+
const REQUEST_FILE = "request.json";
|
|
3624
|
+
const VERDICT_FILE = "verdict.json";
|
|
3625
|
+
const JUDGMENT_FILES = [
|
|
3626
|
+
REQUEST_FILE,
|
|
3627
|
+
VERDICT_FILE,
|
|
3628
|
+
"locator.png",
|
|
3629
|
+
"regions.png",
|
|
3630
|
+
"overview.png"
|
|
3631
|
+
];
|
|
3632
|
+
const JUDGE_MODES = [
|
|
3633
|
+
"ambiguous",
|
|
3634
|
+
"all",
|
|
3635
|
+
"none"
|
|
3636
|
+
];
|
|
3637
|
+
/**
|
|
3638
|
+
* The directory holding a screenshot's judgment.
|
|
3639
|
+
*
|
|
3640
|
+
* Screenshot names are relative paths (`example/button/primary`), so they map
|
|
3641
|
+
* onto nested directories directly; anything that would resolve outside the
|
|
3642
|
+
* judgments root is refused rather than written.
|
|
3643
|
+
*/
|
|
3644
|
+
const judgmentDir = (outputDir, name) => {
|
|
3645
|
+
const root = judgmentsRoot(outputDir);
|
|
3646
|
+
const dir = node_path.default.resolve(root, name);
|
|
3647
|
+
const relative = node_path.default.relative(root, dir);
|
|
3648
|
+
if (!relative || relative.startsWith("..") || node_path.default.isAbsolute(relative)) throw new Error(`Invalid screenshot name for a judgment: ${name}`);
|
|
3649
|
+
return dir;
|
|
3650
|
+
};
|
|
3651
|
+
const exists = async (file) => {
|
|
3652
|
+
try {
|
|
3653
|
+
await node_fs_promises.default.access(file);
|
|
3654
|
+
return true;
|
|
3655
|
+
} catch {
|
|
3656
|
+
return false;
|
|
3657
|
+
}
|
|
3658
|
+
};
|
|
3659
|
+
const readJson = async (file) => {
|
|
3660
|
+
try {
|
|
3661
|
+
return JSON.parse(await node_fs_promises.default.readFile(file, "utf8"));
|
|
3662
|
+
} catch {
|
|
3663
|
+
return;
|
|
3664
|
+
}
|
|
3665
|
+
};
|
|
3666
|
+
const writeJson = async (file, value) => {
|
|
3667
|
+
await node_fs_promises.default.mkdir(node_path.default.dirname(file), { recursive: true });
|
|
3668
|
+
await node_fs_promises.default.writeFile(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
|
|
3669
|
+
};
|
|
3670
|
+
/** Ties a judgment to the exact pair of images it was made about. */
|
|
3671
|
+
const fingerprintImages = async (expectedPath, actualPath) => {
|
|
3672
|
+
const [expected, actual] = await Promise.all([node_fs_promises.default.readFile(expectedPath), node_fs_promises.default.readFile(actualPath)]);
|
|
3673
|
+
return (0, node_crypto.createHash)("sha256").update(expected).update("\0").update(actual).digest("hex");
|
|
3674
|
+
};
|
|
3675
|
+
/**
|
|
3676
|
+
* Read a judge's verdict, accepting both the nested shape blazediff uses
|
|
3677
|
+
* (`{ verdict: { label, headline, rationale }, confidence }`) and a flat one
|
|
3678
|
+
* (`{ label, headline, rationale, confidence }`) — a judge that writes either
|
|
3679
|
+
* should not have its work thrown away over nesting.
|
|
3680
|
+
*/
|
|
3681
|
+
const parseAgentVerdict = (raw) => {
|
|
3682
|
+
if (typeof raw !== "object" || raw === null) return {
|
|
3683
|
+
ok: false,
|
|
3684
|
+
error: "verdict.json is not a JSON object"
|
|
3685
|
+
};
|
|
3686
|
+
const outer = raw;
|
|
3687
|
+
const inner = typeof outer.verdict === "object" && outer.verdict !== null ? outer.verdict : outer;
|
|
3688
|
+
const label = inner.label;
|
|
3689
|
+
if (!isJudgedLabel(label)) return {
|
|
3690
|
+
ok: false,
|
|
3691
|
+
error: `label must be one of regression-likely, intentional-likely, noise-likely (got ${JSON.stringify(label)})`
|
|
3692
|
+
};
|
|
3693
|
+
const headline = typeof inner.headline === "string" && inner.headline.trim() ? inner.headline.trim() : void 0;
|
|
3694
|
+
if (!headline) return {
|
|
3695
|
+
ok: false,
|
|
3696
|
+
error: "headline must be a non-empty string"
|
|
3697
|
+
};
|
|
3698
|
+
const toLines = (value) => Array.isArray(value) ? value.filter((line) => typeof line === "string") : typeof value === "string" && value.trim() ? [value.trim()] : [];
|
|
3699
|
+
const rationale = [...toLines(inner.rationale)];
|
|
3700
|
+
if (inner !== outer) rationale.push(...toLines(outer.rationale));
|
|
3701
|
+
const rawConfidence = outer.confidence ?? inner.confidence;
|
|
3702
|
+
const confidence = typeof rawConfidence === "number" && Number.isFinite(rawConfidence) ? Math.min(1, Math.max(0, rawConfidence)) : void 0;
|
|
3703
|
+
return {
|
|
3704
|
+
ok: true,
|
|
3705
|
+
label,
|
|
3706
|
+
headline,
|
|
3707
|
+
rationale,
|
|
3708
|
+
...confidence !== void 0 ? { confidence } : {}
|
|
3709
|
+
};
|
|
3710
|
+
};
|
|
3711
|
+
const readSize = async (file) => {
|
|
3712
|
+
const { width = 0, height = 0 } = await (0, sharp.default)(file).metadata();
|
|
3713
|
+
return {
|
|
3714
|
+
width,
|
|
3715
|
+
height
|
|
3716
|
+
};
|
|
3717
|
+
};
|
|
3718
|
+
const toAgentRegions = (regions) => [...regions].sort((a, b) => b.pixelCount - a.pixelCount).map((region, index) => ({
|
|
3719
|
+
index: index + 1,
|
|
3720
|
+
bbox: {
|
|
3721
|
+
x: region.bbox.x,
|
|
3722
|
+
y: region.bbox.y,
|
|
3723
|
+
width: region.bbox.width,
|
|
3724
|
+
height: region.bbox.height
|
|
3725
|
+
},
|
|
3726
|
+
pixelCount: region.pixelCount,
|
|
3727
|
+
percentage: region.percentage,
|
|
3728
|
+
position: region.position,
|
|
3729
|
+
shape: region.shape,
|
|
3730
|
+
changeType: normalizeChangeType(region.changeType),
|
|
3731
|
+
confidence: region.confidence
|
|
3732
|
+
}));
|
|
3733
|
+
/**
|
|
3734
|
+
* The interpretation a capture already persisted, or a fresh one.
|
|
3735
|
+
*
|
|
3736
|
+
* `diff.interpret` is off by default, so most changed screenshots arrive
|
|
3737
|
+
* without one; computing it here means agent review works on any project
|
|
3738
|
+
* rather than only on those that opted into interpretation at capture time.
|
|
3739
|
+
*/
|
|
3740
|
+
const interpretationFor = async (screenshot, expectedPath, actualPath, diff) => {
|
|
3741
|
+
if (screenshot.diffMeta?.interpretation) return screenshot.diffMeta.interpretation;
|
|
3742
|
+
const pixel = diff && diff.type !== "gmsd" ? diff : void 0;
|
|
3743
|
+
try {
|
|
3744
|
+
return await (0, _blazediff_interpret_native.interpret)(expectedPath, actualPath, void 0, {
|
|
3745
|
+
source: "pixel",
|
|
3746
|
+
threshold: pixel?.threshold,
|
|
3747
|
+
antialiasing: pixel?.includeAA ?? false
|
|
3748
|
+
});
|
|
3749
|
+
} catch {
|
|
3750
|
+
return;
|
|
3751
|
+
}
|
|
3752
|
+
};
|
|
3753
|
+
const JUDGE_INSTRUCTIONS = [
|
|
3754
|
+
"Read locator.png and regions.png together. locator.png outlines every region (numbered) on a thumbnail; regions.png stacks one [expected | actual] row per region, in `regions` order.",
|
|
3755
|
+
"Open overview.png when it exists instead — the image dimensions changed, so no regions could be located.",
|
|
3756
|
+
"Only open paths.expected / paths.actual / paths.diff (full size) when a change clearly continues outside its crop.",
|
|
3757
|
+
"Write verdict.json next to this file, or run `cappa agent judge <name> --label <label> --headline <text>`."
|
|
3758
|
+
];
|
|
3759
|
+
const VERDICT_SCHEMA = {
|
|
3760
|
+
label: "regression-likely | intentional-likely | noise-likely",
|
|
3761
|
+
headline: "one line describing what changed",
|
|
3762
|
+
rationale: ["short reasons"],
|
|
3763
|
+
confidence: "0..1"
|
|
3764
|
+
};
|
|
3765
|
+
const analyseChanged = async (screenshot, options, createdAt) => {
|
|
3766
|
+
const { outputDir } = options;
|
|
3767
|
+
const expectedPath = node_path.default.resolve(outputDir, screenshot.expectedPath);
|
|
3768
|
+
const actualPath = node_path.default.resolve(outputDir, screenshot.actualPath);
|
|
3769
|
+
const diffPath = node_path.default.resolve(outputDir, screenshot.diffPath);
|
|
3770
|
+
const [expectedSize, actualSize, diffExists] = await Promise.all([
|
|
3771
|
+
readSize(expectedPath),
|
|
3772
|
+
readSize(actualPath),
|
|
3773
|
+
exists(diffPath)
|
|
3774
|
+
]);
|
|
3775
|
+
const differentSizes = expectedSize.width !== actualSize.width || expectedSize.height !== actualSize.height;
|
|
3776
|
+
const interpretation = differentSizes ? void 0 : await interpretationFor(screenshot, expectedPath, actualPath, options.diff);
|
|
3777
|
+
const percentDifference = screenshot.diffMeta?.percentDifference ?? interpretation?.diffPercentage;
|
|
3778
|
+
const numDiffPixels = screenshot.diffMeta?.numDiffPixels ?? interpretation?.diffCount;
|
|
3779
|
+
const regions = toAgentRegions(interpretation?.regions ?? []);
|
|
3780
|
+
const heuristic = deriveVerdict({
|
|
3781
|
+
percentDifference,
|
|
3782
|
+
numDiffPixels,
|
|
3783
|
+
interpretation,
|
|
3784
|
+
differentSizes
|
|
3785
|
+
});
|
|
3786
|
+
const entry = {
|
|
3787
|
+
name: screenshot.name,
|
|
3788
|
+
category: "changed",
|
|
3789
|
+
...screenshot.taskId ? {
|
|
3790
|
+
taskId: screenshot.taskId,
|
|
3791
|
+
plugin: screenshot.plugin
|
|
3792
|
+
} : {},
|
|
3793
|
+
paths: {
|
|
3794
|
+
expected: expectedPath,
|
|
3795
|
+
actual: actualPath,
|
|
3796
|
+
...diffExists ? { diff: diffPath } : {}
|
|
3797
|
+
},
|
|
3798
|
+
percentDifference,
|
|
3799
|
+
numDiffPixels,
|
|
3800
|
+
dimensions: {
|
|
3801
|
+
expected: expectedSize,
|
|
3802
|
+
actual: actualSize
|
|
3803
|
+
},
|
|
3804
|
+
severity: interpretation?.severity?.toLowerCase(),
|
|
3805
|
+
summary: interpretation?.summary,
|
|
3806
|
+
regions,
|
|
3807
|
+
heuristic,
|
|
3808
|
+
verdict: {
|
|
3809
|
+
...heuristic,
|
|
3810
|
+
source: "heuristic"
|
|
3811
|
+
},
|
|
3812
|
+
pending: false
|
|
3813
|
+
};
|
|
3814
|
+
const dir = judgmentDir(outputDir, screenshot.name);
|
|
3815
|
+
const requestPath = node_path.default.join(dir, REQUEST_FILE);
|
|
3816
|
+
const verdictPath = node_path.default.join(dir, VERDICT_FILE);
|
|
3817
|
+
if (!(options.judge === "all" || options.judge === "ambiguous" && heuristic.label === "ambiguous" || await exists(requestPath))) return entry;
|
|
3818
|
+
const fingerprint = await fingerprintImages(expectedPath, actualPath);
|
|
3819
|
+
const previous = await readJson(requestPath);
|
|
3820
|
+
if (previous && previous.fingerprint !== fingerprint) await clearJudgmentFiles(dir);
|
|
3821
|
+
await node_fs_promises.default.mkdir(dir, { recursive: true });
|
|
3822
|
+
const judgment = {
|
|
3823
|
+
dir,
|
|
3824
|
+
request: requestPath,
|
|
3825
|
+
verdict: verdictPath
|
|
3826
|
+
};
|
|
3827
|
+
if (differentSizes) judgment.overview = await renderOverview({
|
|
3828
|
+
expectedPath,
|
|
3829
|
+
actualPath,
|
|
3830
|
+
outDir: dir
|
|
3831
|
+
});
|
|
3832
|
+
else {
|
|
3833
|
+
const tiles = await renderJudgmentTiles({
|
|
3834
|
+
expectedPath,
|
|
3835
|
+
actualPath,
|
|
3836
|
+
diffPath: diffExists ? diffPath : void 0,
|
|
3837
|
+
regions: regions.map((region) => region.bbox),
|
|
3838
|
+
outDir: dir,
|
|
3839
|
+
maxRegions: options.maxTileRegions
|
|
3840
|
+
});
|
|
3841
|
+
if (tiles.locator) judgment.locator = tiles.locator;
|
|
3842
|
+
if (tiles.regions) judgment.regions = tiles.regions;
|
|
3843
|
+
}
|
|
3844
|
+
entry.judgment = judgment;
|
|
3845
|
+
await writeJson(requestPath, {
|
|
3846
|
+
version: 1,
|
|
3847
|
+
name: entry.name,
|
|
3848
|
+
taskId: entry.taskId,
|
|
3849
|
+
plugin: entry.plugin,
|
|
3850
|
+
fingerprint,
|
|
3851
|
+
createdAt,
|
|
3852
|
+
instructions: JUDGE_INSTRUCTIONS,
|
|
3853
|
+
verdictSchema: VERDICT_SCHEMA,
|
|
3854
|
+
heuristic,
|
|
3855
|
+
percentDifference,
|
|
3856
|
+
numDiffPixels,
|
|
3857
|
+
dimensions: entry.dimensions,
|
|
3858
|
+
severity: entry.severity,
|
|
3859
|
+
summary: entry.summary,
|
|
3860
|
+
regions,
|
|
3861
|
+
paths: {
|
|
3862
|
+
locator: judgment.locator,
|
|
3863
|
+
regions: judgment.regions,
|
|
3864
|
+
overview: judgment.overview,
|
|
3865
|
+
expected: expectedPath,
|
|
3866
|
+
actual: actualPath,
|
|
3867
|
+
diff: entry.paths.diff,
|
|
3868
|
+
verdict: verdictPath
|
|
3869
|
+
}
|
|
3870
|
+
});
|
|
3871
|
+
if (!await exists(verdictPath)) {
|
|
3872
|
+
entry.pending = true;
|
|
3873
|
+
return entry;
|
|
3874
|
+
}
|
|
3875
|
+
const parsed = parseAgentVerdict(await readJson(verdictPath));
|
|
3876
|
+
if (!parsed.ok) {
|
|
3877
|
+
entry.pending = true;
|
|
3878
|
+
entry.verdictError = parsed.error;
|
|
3879
|
+
return entry;
|
|
3880
|
+
}
|
|
3881
|
+
entry.verdict = {
|
|
3882
|
+
label: parsed.label,
|
|
3883
|
+
headline: parsed.headline,
|
|
3884
|
+
rationale: parsed.rationale,
|
|
3885
|
+
action: ACTION_BY_LABEL[parsed.label],
|
|
3886
|
+
source: "agent",
|
|
3887
|
+
...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
|
|
3888
|
+
};
|
|
3889
|
+
return entry;
|
|
3890
|
+
};
|
|
3891
|
+
const clearJudgmentFiles = async (dir) => {
|
|
3892
|
+
await Promise.all(JUDGMENT_FILES.map((file) => node_fs_promises.default.rm(node_path.default.join(dir, file), { force: true })));
|
|
3893
|
+
};
|
|
3894
|
+
/**
|
|
3895
|
+
* Remove a screenshot's judgment — after it was approved, or because it is no
|
|
3896
|
+
* longer changed. Only the judgment's own files go: a directory can also be
|
|
3897
|
+
* the parent of another screenshot's judgment (`button` and `button/primary`).
|
|
3898
|
+
*/
|
|
3899
|
+
const clearJudgment = async (outputDir, name) => {
|
|
3900
|
+
const dir = judgmentDir(outputDir, name);
|
|
3901
|
+
await clearJudgmentFiles(dir);
|
|
3902
|
+
await removeEmptyDirs(dir, judgmentsRoot(outputDir));
|
|
3903
|
+
};
|
|
3904
|
+
/** Remove `dir` and its parents up to (excluding) `root` while empty. */
|
|
3905
|
+
const removeEmptyDirs = async (dir, root) => {
|
|
3906
|
+
let current = dir;
|
|
3907
|
+
while (current !== root && current.startsWith(root)) {
|
|
3908
|
+
try {
|
|
3909
|
+
await node_fs_promises.default.rmdir(current);
|
|
3910
|
+
} catch {
|
|
3911
|
+
return;
|
|
3912
|
+
}
|
|
3913
|
+
current = node_path.default.dirname(current);
|
|
3914
|
+
}
|
|
3915
|
+
};
|
|
3916
|
+
const listRequestDirs = async (root) => {
|
|
3917
|
+
if (!await exists(root)) return [];
|
|
3918
|
+
return (await Array.fromAsync(node_fs_promises.default.glob(`**/${REQUEST_FILE}`, { cwd: root }))).map((file) => node_path.default.resolve(root, node_path.default.dirname(file)));
|
|
3919
|
+
};
|
|
3920
|
+
/** Drop judgments for screenshots that no longer need one. */
|
|
3921
|
+
const pruneJudgments = async (outputDir, keep) => {
|
|
3922
|
+
const root = judgmentsRoot(outputDir);
|
|
3923
|
+
for (const dir of await listRequestDirs(root)) {
|
|
3924
|
+
if (keep.has(dir)) continue;
|
|
3925
|
+
await clearJudgmentFiles(dir);
|
|
3926
|
+
await removeEmptyDirs(dir, root);
|
|
3927
|
+
}
|
|
3928
|
+
};
|
|
3929
|
+
/**
|
|
3930
|
+
* Analyse every non-passing screenshot, write judgment requests for the ones
|
|
3931
|
+
* that need a judge, apply any verdicts already written, and persist the
|
|
3932
|
+
* full report to `<outputDir>/.cappa-agent/report.json`.
|
|
3933
|
+
*/
|
|
3934
|
+
const runAgentCheck = async (options) => {
|
|
3935
|
+
const outputDir = node_path.default.resolve(options.outputDir);
|
|
3936
|
+
const judge = options.judge ?? "ambiguous";
|
|
3937
|
+
const createdAt = (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
|
|
3938
|
+
const screenshots = await collectScreenshots(outputDir);
|
|
3939
|
+
await node_fs_promises.default.mkdir(agentDir(outputDir), { recursive: true });
|
|
3940
|
+
await node_fs_promises.default.writeFile(node_path.default.join(agentDir(outputDir), ".gitignore"), "*\n");
|
|
3941
|
+
const changed = screenshots.filter((s) => s.category === "changed");
|
|
3942
|
+
const changedEntries = await mapWithConcurrency(options.concurrency ?? 4, changed, (screenshot) => analyseChanged(screenshot, {
|
|
3943
|
+
...options,
|
|
3944
|
+
outputDir,
|
|
3945
|
+
judge
|
|
3946
|
+
}, createdAt));
|
|
3947
|
+
await pruneJudgments(outputDir, new Set(changedEntries.flatMap((entry) => entry.judgment ? [entry.judgment.dir] : [])));
|
|
3948
|
+
const otherEntries = screenshots.flatMap((s) => {
|
|
3949
|
+
if (s.category === "new") return [{
|
|
3950
|
+
name: s.name,
|
|
3951
|
+
category: "new",
|
|
3952
|
+
...s.taskId ? {
|
|
3953
|
+
taskId: s.taskId,
|
|
3954
|
+
plugin: s.plugin
|
|
3955
|
+
} : {},
|
|
3956
|
+
paths: { actual: node_path.default.resolve(outputDir, s.actualPath) },
|
|
3957
|
+
pending: false
|
|
3958
|
+
}];
|
|
3959
|
+
if (s.category === "deleted") return [{
|
|
3960
|
+
name: s.name,
|
|
3961
|
+
category: "deleted",
|
|
3962
|
+
paths: { expected: node_path.default.resolve(outputDir, s.expectedPath) },
|
|
3963
|
+
pending: false
|
|
3964
|
+
}];
|
|
3965
|
+
return [];
|
|
3966
|
+
});
|
|
3967
|
+
const entries = [...changedEntries, ...otherEntries];
|
|
3968
|
+
const count = (category) => screenshots.filter((s) => s.category === category).length;
|
|
3969
|
+
const report = {
|
|
3970
|
+
version: 1,
|
|
3971
|
+
createdAt,
|
|
3972
|
+
outputDir,
|
|
3973
|
+
reportPath: agentReportPath(outputDir),
|
|
3974
|
+
judge,
|
|
3975
|
+
totals: {
|
|
3976
|
+
total: screenshots.length,
|
|
3977
|
+
passed: count("passed"),
|
|
3978
|
+
changed: count("changed"),
|
|
3979
|
+
new: count("new"),
|
|
3980
|
+
deleted: count("deleted"),
|
|
3981
|
+
pendingJudgments: entries.filter((entry) => entry.pending).length
|
|
3982
|
+
},
|
|
3983
|
+
entries
|
|
3984
|
+
};
|
|
3985
|
+
await writeJson(report.reportPath, report);
|
|
3986
|
+
return report;
|
|
3987
|
+
};
|
|
3988
|
+
/** Read the report the last {@link runAgentCheck} wrote, if any. */
|
|
3989
|
+
const readAgentReport = async (outputDir) => {
|
|
3990
|
+
const raw = await readJson(agentReportPath(outputDir));
|
|
3991
|
+
return raw?.version === 1 ? raw : void 0;
|
|
3992
|
+
};
|
|
3993
|
+
/**
|
|
3994
|
+
* The report as an agent should first see it: one line of state per
|
|
3995
|
+
* screenshot, with the detail left in `report.json` and the judgment
|
|
3996
|
+
* requests for when it is actually needed.
|
|
3997
|
+
*/
|
|
3998
|
+
const toSlimAgentReport = (report) => ({
|
|
3999
|
+
reportPath: report.reportPath,
|
|
4000
|
+
...report.totals,
|
|
4001
|
+
results: report.entries.map((entry) => ({
|
|
4002
|
+
name: entry.name,
|
|
4003
|
+
category: entry.category,
|
|
4004
|
+
...entry.verdict ? { verdict: {
|
|
4005
|
+
label: entry.verdict.label,
|
|
4006
|
+
headline: entry.verdict.headline,
|
|
4007
|
+
action: entry.verdict.action,
|
|
4008
|
+
source: entry.verdict.source
|
|
4009
|
+
} } : {},
|
|
4010
|
+
...entry.pending ? { pending: true } : {},
|
|
4011
|
+
...entry.pending && entry.judgment ? { judgment: entry.judgment.dir } : {},
|
|
4012
|
+
...entry.verdictError ? { verdictError: entry.verdictError } : {}
|
|
4013
|
+
}))
|
|
4014
|
+
});
|
|
4015
|
+
/**
|
|
4016
|
+
* Record a judge's verdict for a screenshot with a pending request — the
|
|
4017
|
+
* validated alternative to hand-writing `verdict.json`.
|
|
4018
|
+
*/
|
|
4019
|
+
const writeAgentVerdict = async (outputDir, name, input) => {
|
|
4020
|
+
const dir = judgmentDir(outputDir, name);
|
|
4021
|
+
if (!await exists(node_path.default.join(dir, REQUEST_FILE))) throw new Error(`No judgment request for "${name}" — run \`cappa agent check\` first (use --judge all to request one for any changed screenshot).`);
|
|
4022
|
+
const parsed = parseAgentVerdict(input);
|
|
4023
|
+
if (!parsed.ok) throw new Error(parsed.error);
|
|
4024
|
+
const verdictPath = node_path.default.join(dir, VERDICT_FILE);
|
|
4025
|
+
await writeJson(verdictPath, {
|
|
4026
|
+
name,
|
|
4027
|
+
verdict: {
|
|
4028
|
+
label: parsed.label,
|
|
4029
|
+
headline: parsed.headline,
|
|
4030
|
+
rationale: parsed.rationale,
|
|
4031
|
+
action: ACTION_BY_LABEL[parsed.label]
|
|
4032
|
+
},
|
|
4033
|
+
...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
|
|
4034
|
+
});
|
|
4035
|
+
return verdictPath;
|
|
4036
|
+
};
|
|
4037
|
+
//#endregion
|
|
4038
|
+
exports.ACTION_BY_LABEL = ACTION_BY_LABEL;
|
|
4039
|
+
exports.AGENT_DIRNAME = AGENT_DIRNAME;
|
|
4040
|
+
exports.AGENT_REPORT_VERSION = AGENT_REPORT_VERSION;
|
|
3185
4041
|
exports.CONSOLE_LOG_LEVELS = CONSOLE_LOG_LEVELS;
|
|
3186
4042
|
exports.CaptureRunner = CaptureRunner;
|
|
3187
4043
|
exports.DEFAULT_DEBOUNCE_MS = DEFAULT_DEBOUNCE_MS;
|
|
@@ -3189,42 +4045,65 @@ exports.DEFAULT_IGNORED_DIRS = DEFAULT_IGNORED_DIRS;
|
|
|
3189
4045
|
exports.DEFAULT_MAX_TASKS = DEFAULT_MAX_TASKS;
|
|
3190
4046
|
exports.ENGINE_ERROR_CODES = ENGINE_ERROR_CODES;
|
|
3191
4047
|
exports.FsScreenshotStore = FsScreenshotStore;
|
|
4048
|
+
exports.JUDGED_LABELS = JUDGED_LABELS;
|
|
4049
|
+
exports.JUDGE_MODES = JUDGE_MODES;
|
|
3192
4050
|
exports.LocalEngine = LocalEngine;
|
|
3193
4051
|
exports.MANIFEST_FILENAME = MANIFEST_FILENAME;
|
|
3194
4052
|
exports.MANIFEST_VERSION = MANIFEST_VERSION;
|
|
3195
4053
|
exports.RunInProgressError = RunInProgressError;
|
|
3196
4054
|
exports.RunStore = RunStore;
|
|
4055
|
+
exports.SUB_PERCEPTUAL_PERCENT = SUB_PERCEPTUAL_PERCENT;
|
|
3197
4056
|
exports.ScreenshotFileSystem = ScreenshotFileSystem;
|
|
3198
4057
|
exports.ScreenshotTool = ScreenshotTool;
|
|
3199
4058
|
exports.UnknownTargetsError = UnknownTargetsError;
|
|
4059
|
+
exports.VERDICT_LABELS = VERDICT_LABELS;
|
|
3200
4060
|
exports.WarmBrowser = WarmBrowser;
|
|
3201
4061
|
exports.WatchInProgressError = WatchInProgressError;
|
|
3202
4062
|
exports.WatchSession = WatchSession;
|
|
4063
|
+
exports.agentDir = agentDir;
|
|
4064
|
+
exports.agentReportPath = agentReportPath;
|
|
3203
4065
|
exports.attachConsoleLogging = attachConsoleLogging;
|
|
4066
|
+
exports.buildHeadline = buildHeadline;
|
|
4067
|
+
exports.clearJudgment = clearJudgment;
|
|
3204
4068
|
exports.collectScreenshots = collectScreenshots;
|
|
3205
4069
|
exports.compareImages = compareImages;
|
|
3206
4070
|
exports.compareImagesGMSD = compareImagesGMSD;
|
|
4071
|
+
exports.contextPadding = contextPadding;
|
|
3207
4072
|
exports.defineConfig = defineConfig;
|
|
4073
|
+
exports.deriveVerdict = deriveVerdict;
|
|
3208
4074
|
exports.didScreenshotFail = didScreenshotFail;
|
|
3209
4075
|
exports.filterTasks = filterTasks;
|
|
4076
|
+
exports.fingerprintImages = fingerprintImages;
|
|
3210
4077
|
exports.getDeletedScreenshots = getDeletedScreenshots;
|
|
3211
4078
|
exports.groupScreenshots = groupScreenshots;
|
|
3212
4079
|
exports.imagesMatch = imagesMatch;
|
|
3213
4080
|
exports.imagesMatchGMSD = imagesMatchGMSD;
|
|
4081
|
+
exports.isJudgedLabel = isJudgedLabel;
|
|
3214
4082
|
exports.isRunInProgressError = isRunInProgressError;
|
|
3215
4083
|
exports.isUnknownTargetsError = isUnknownTargetsError;
|
|
4084
|
+
exports.isVerdictLabel = isVerdictLabel;
|
|
3216
4085
|
exports.isWatchInProgressError = isWatchInProgressError;
|
|
4086
|
+
exports.judgmentDir = judgmentDir;
|
|
3217
4087
|
exports.mapWithConcurrency = mapWithConcurrency;
|
|
3218
4088
|
exports.mergeCaptureManifest = mergeCaptureManifest;
|
|
4089
|
+
exports.normalizeChangeType = normalizeChangeType;
|
|
4090
|
+
exports.padAndClamp = padAndClamp;
|
|
4091
|
+
exports.parseAgentVerdict = parseAgentVerdict;
|
|
4092
|
+
exports.readAgentReport = readAgentReport;
|
|
3219
4093
|
exports.readCaptureManifest = readCaptureManifest;
|
|
3220
4094
|
exports.readDiffMeta = readDiffMeta;
|
|
3221
4095
|
exports.recordCaptureOrigins = recordCaptureOrigins;
|
|
4096
|
+
exports.renderJudgmentTiles = renderJudgmentTiles;
|
|
4097
|
+
exports.renderOverview = renderOverview;
|
|
4098
|
+
exports.runAgentCheck = runAgentCheck;
|
|
3222
4099
|
exports.sanitizeScreenshotFilename = sanitizeScreenshotFilename;
|
|
3223
4100
|
exports.selectTasks = selectTasks;
|
|
3224
4101
|
exports.toConsoleLogLevel = toConsoleLogLevel;
|
|
3225
4102
|
exports.toDiffMetaPath = toDiffMetaPath;
|
|
3226
4103
|
exports.toManifestKey = toManifestKey;
|
|
3227
4104
|
exports.toSerializedError = toSerializedError;
|
|
4105
|
+
exports.toSlimAgentReport = toSlimAgentReport;
|
|
3228
4106
|
exports.toTaskStatus = toTaskStatus;
|
|
4107
|
+
exports.writeAgentVerdict = writeAgentVerdict;
|
|
3229
4108
|
|
|
3230
4109
|
//# sourceMappingURL=index.cjs.map
|