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